audio_stream_out Struct Reference

audio_stream_out Struct Reference

#include < audio.h >

Data Fields

struct audio_stream   common
uint32_t(*  get_latency )(const struct audio_stream_out *stream)
int(*  set_volume )(struct audio_stream_out *stream, float left, float right)
ssize_t(*  write )(struct audio_stream_out *stream, const void *buffer, size_t bytes)
int(*  get_render_position )(const struct audio_stream_out *stream, uint32_t *dsp_frames)
int(*  get_next_write_timestamp )(const struct audio_stream_out *stream, int64_t *timestamp)
int(*  set_callback )(struct audio_stream_out *stream, stream_callback_t callback, void *cookie)
int(*  pause )(struct audio_stream_out *stream)
int(*  resume )(struct audio_stream_out *stream)
int(*  drain )(struct audio_stream_out *stream, audio_drain_type_t type)
int(*  flush )(struct audio_stream_out *stream)
int(*  get_presentation_position )(const struct audio_stream_out *stream, uint64_t *frames, struct timespec *timestamp)

Detailed Description

audio_stream_out is the abstraction interface for the audio output hardware.

It provides information about various properties of the audio output hardware driver.

Definition at line 276 of file audio.h .

Field Documentation

struct audio_stream common

Common methods of the audio stream out. This must be the first member of audio_stream_out as users of this structure will cast a audio_stream to audio_stream_out pointer in contexts where it's known the audio_stream references an audio_stream_out .

Definition at line 282 of file audio.h .

int(* drain)(struct audio_stream_out *stream, audio_drain_type_t type)

Requests notification when data buffered by the driver/hardware has been played. If set_callback() has previously been called to enable non-blocking mode, the drain() must not block, instead it should return quickly and completion of the drain is notified through the callback. If set_callback() has not been called, the drain() must block until completion. If type==AUDIO_DRAIN_ALL, the drain completes when all previously written data has been played. If type==AUDIO_DRAIN_EARLY_NOTIFY, the drain completes shortly before all data for the current track has played to allow time for the framework to perform a gapless track switch.

Drain must return immediately on stop() and flush() call

Implementation of this function is mandatory for offloaded playback.

Definition at line 372 of file audio.h .

int(* flush)(struct audio_stream_out *stream)

Notifies to the audio driver to flush the queued data. Stream must already be paused before calling flush() .

Implementation of this function is mandatory for offloaded playback.

Definition at line 380 of file audio.h .

uint32_t(* get_latency)(const struct audio_stream_out *stream)

Return the audio hardware driver estimated latency in milliseconds.

Definition at line 287 of file audio.h .

int(* get_next_write_timestamp)(const struct audio_stream_out *stream, int64_t *timestamp)

get the local time at which the next write to the audio driver will be presented. The units are microseconds, where the epoch is decided by the local audio HAL.

Definition at line 324 of file audio.h .

int(* get_presentation_position)(const struct audio_stream_out *stream, uint64_t *frames, struct timespec *timestamp)

Return a recent count of the number of audio frames presented to an external observer. This excludes frames which have been written but are still in the pipeline. The count is not reset to zero when output enters standby. Also returns the value of CLOCK_MONOTONIC as of this presentation count. The returned count is expected to be 'recent', but does not need to be the most recent possible value. However, the associated time should correspond to whatever count is returned. Example: assume that N+M frames have been presented, where M is a 'small' number. Then it is permissible to return N instead of N+M, and the timestamp should correspond to N rather than N+M. The terms 'recent' and 'small' are not defined. They reflect the quality of the implementation.

3.0 and higher only.

Definition at line 398 of file audio.h .

int(* get_render_position)(const struct audio_stream_out *stream, uint32_t *dsp_frames)

Definition at line 317 of file audio.h .

int(* pause)(struct audio_stream_out *stream)

Notifies to the audio driver to stop playback however the queued buffers are retained by the hardware. Useful for implementing pause/resume. Empty implementation if not supported however should be implemented for hardware with non-trivial latency. In the pause state audio hardware could still be using power. User may consider calling suspend after a timeout.

Implementation of this function is mandatory for offloaded playback.

Definition at line 345 of file audio.h .

int(* resume)(struct audio_stream_out *stream)

Notifies to the audio driver to resume playback following a pause. Returns error if called without matching pause.

Implementation of this function is mandatory for offloaded playback.

Definition at line 353 of file audio.h .

int(* set_callback)(struct audio_stream_out *stream, stream_callback_t callback, void *cookie)

set the callback function for notifying completion of non-blocking write and drain. Calling this function implies that all future write() and drain() must be non-blocking and use the callback to signal completion.

Definition at line 333 of file audio.h .

int(* set_volume)(struct audio_stream_out *stream, float left, float right)

Use this method in situations where audio mixing is done in the hardware. This method serves as a direct interface with hardware, allowing you to directly set the volume as apposed to via the framework. This method might produce multiple PCM outputs or hardware accelerated codecs, such as MP3 or AAC.

Definition at line 296 of file audio.h .

ssize_t(* write)(struct audio_stream_out *stream, const void *buffer, size_t bytes)

Write audio buffer to driver. Returns number of bytes written, or a negative status_t. If at least one frame was written successfully prior to the error, it is suggested that the driver return that successful (short) byte count and then return an error in the subsequent call.

If set_callback() has previously been called to enable non-blocking mode the write() is not allowed to block. It must write only the number of bytes that currently fit in the driver/hardware buffer and then return this byte count. If this is less than the requested write size the callback function must be called when more space is available in the driver/hardware buffer.

Definition at line 311 of file audio.h .

The documentation for this struct was generated from the following file:
  • hardware/libhardware/include/hardware/ audio.h