ISMD Audio Sink feature
-=---------------------

The feature named ismd_audio_sink is intended to manage the rendering of
audio streams in raw PCM or compressed form using the SMD layer.

Overview
--------

As GStreamer feature it will expose in the caps the available formats
after a discovery in the system using ismd_audio_codec_available API.

The following diagram shows an overview on the architecture of the element.

      +-------------------------------------------------------------------+
      | ISmdGstAudioSink                                                  |
      |                 +----------------------------------------------+  |
      |                 | AUDIO PROCESSOR                              |  |
      |                 | ismd_audio_open_global_processor             |  |
      |                 | or ismd_audio_open_processor                 |  |
      |                 |                                              |  |
+----------+     +------------+                                        |  |
| sink pad |-----| input_port | <- ismd_audio_add_input_port           |  |
+----------+     +------------+                                        |  |
      |                 |                                              |  |
      |                 |                                              |  |
      |                 |               ismd_audio_add_phys_output     |  |
      |                 |              _____________\/____________     |  |
      |                 |             /                           \    |  |
      |                 |                                     +---+    |  |
      |                 |             +---+   +---+   +---+   | S |    |  |
      |                 +-------------| H |---| I |---| I |---| P |----+  |
      | +--------------+              | D |   | 2 |   | 2 |   | D |       |
      | | ISmdGstClock |              | M |   | S |   | S |   | I |       |
      | +--------------+              | I |   | 0 |   | 1 |   | F |       |
      |      |                        +---+   +---+   +---+   +---+       |
      +------|------------------------------------------------------------+
             |
             +-> The element is a clock provider and provides a ISmdGstClock to
                 the pipeline.

Properties
----------

The element will use the GOobject property mechanism to permit some level of
configuration. The following is a description on the currently implemented
properties.

global-processor: boolean property that permit specify if the global processor
is going to be used. By default set to TRUE.

sync: boolean property that permit specify if the rendering will be synchronized
with the timestamp information provided in the stream and the selected clock.
By default set to TRUE.

audio-output-hdmi: enumeration { AUTO, OFF, PCM, PASSTHROUGH, AC3, DTS }
  AUTO: auto select the best output format according to the input stream and 
  the output capabilities detected. For example perform ac3 pass through if
  input is ac3 and the hdmi connected device can support ac3 directly.
  OFF: disable this output port.
  PCM: output PCM data that provides the best quality according to
  the capabilities accepted by the HDMI device connected and the input 
  format. Implies select the best sample rate used by the resampler.
  PASSTHROUGH: force pass through.
  AC3: pass through if input is AC3 and transcode into AC3 for other cases.
  For this to work is required the AC3 encoder.
  DTS: pass through if input is DTS and transcode into DTS for other cases.
  For this to work is required the DTS encoder.

audio-output-i2s0: enumeration { OFF, PCM }
  OFF: disable this output port.
  PCM: output PCM data that provides the best quality. Keep the sample rate
  of input data.

audio-output-i2s1: enumeration { OFF, PCM }
  Same as audio-output-i2s0.
  
audio-output-spdif: enumeration { AUTO, OFF, PCM, PASSTHROUGH, AC3, DTS }
  Same as audio-output-hdmi.

render-delay: integer range from 0 to 255 milliseconds.
  Permit specify a delay that will be applied to the rendering.
  By default set to 0.

mute: boolean property that permit mute all outputs.

volume: float range from 0.0 to 1.0
  Permit specify a volume factor from 0% to 100%.

Clock
-----

The element creates an instance of ISmdGstClock and provides it to the pipeline
on request.

State changes
-------------

The feature performs the following actions during a state change:

 - NULL -> READY:
    - ismd_audio_open_global_processor or ismd_audio_open_processor depending
      on the value of global-processor property.
    - ismd_audio_add_input_port to create the input port on the processor.
    - ismd_audio_mute if the mute property was set to TRUE.
    - set the volume specified with the volume property.
    - discover the capabilities of the HDMI device connected(supported formats,
      sample rates and sample widths).
      
 - READY -> PAUSED:
    - ismd_dev_set_state (device, ISMD_DEV_STATE_PAUSE).
    - report GST_STATE_CHANGE_ASYNC and start prerolling.

 - PAUSED -> PLAYING:
    - ismd_dev_set_clock with the pipeline negotiated SMD clock.
    - ismd_dev_set_stream_base_time with the pipeline distributed base time.
    - ismd_dev_set_state (device, ISMD_DEV_STATE_PLAY).

 - PLAYING -> PAUSED:
    - ismd_dev_set_state (device, ISMD_DEV_STATE_PAUSE). 

 - PAUSED -> READY:
    - ismd_dev_set_state (device, ISMD_DEV_STATE_STOP). 
    - ismd_dev_flush to flush all remaining data in the device.

 - READY -> NULL:
    - ismd_audio_remove_output to remove the output ports.
    - ismd_audio_remove_input to remove the input port.
    - ismd_audio_close_processor to close the processor.

This feature is capable to do prerolling and the state change from READY to 
PAUSED is commited when the first SMD buffer is going to be pushed into the
input port.

Configuration on data flow
--------------------------

The output ports are recreated each time that a new kind of data flow reaches
the sink. This behaviour is implemented in the setcaps callback of the sink pad,
when new caps trigger it the following operations take place:

- collect data from the caps.
- ismd_dev_set_state (device, ISMD_DEV_STATE_PAUSE) if was in PLAYING state.
- ismd_audio_input_set_data_format to configure the input format (PCM,AAC,...).
- on ISMD_AUDIO_MEDIA_FMT_WM9: ismd_audio_input_set_wma_format.
- on ISMD_AUDIO_MEDIA_FMT_PCM: ismd_audio_input_set_pcm_format.
- ismd_audio_input_set_timing_accuracy.
- ismd_audio_input_set_as_primary.
- for out in {HDMI, I2S0, I2S1, SPDIF} do ismd_configure_output (out).
- set_audio_pll_freq to configure the PLL family according the in sample rate.
- for out in {HDMI, I2S0, I2S1, SPDIF} do ismd_audio_output_enable (out).
- ismd_dev_set_state (device, ISMD_DEV_STATE_PLAY) if was in PLAYING state.

The meta method ismd_configure_output is intended to decide the best
configuration taking into account the collected data about the stream and
the known capabilities of the output port. It performs the following actions:

- ismd_audio_add_phys_output.
- on out != HDMI do ismd_audio_output_set_external_bit_clock_div.

Usage examples
--------------

$ gst-launch-0.10 audiotestsrc ! ismd_audio_sink

$ gst-launch-0.10 filesrc location=test.aac ! typefind ! \
    ismd_audio_sink sync=false

ToDo
----

Controling interfaces: implement interfaces GstMixer and GstStreamVolume
  to be able configure the element through it and have better integration
  with playbin2.

Request src pad for visualization: add the capability of requesting a
  src pad pushing PCM stereo data to be used for audio visualization in
  the application. Implementation would be similar to the original Intel
  feature named ismd_audio_dec.

Parsers for compressed formats: add bitstream parsing for accurate
time stamping on the SMD buffers and improve the seeking.

