Merge "Minor fixes in native media documentation"
diff --git a/docs/STABLE-APIS.html b/docs/STABLE-APIS.html
index ec61aa7..6b02531 100644
--- a/docs/STABLE-APIS.html
+++ b/docs/STABLE-APIS.html
@@ -32,6 +32,7 @@
android-7 -> Official Android 2.1 system images
android-8 -> Official Android 2.2 system images
android-9 -> Official Android 2.3 system images
+ android-14 -> Official Android 4.0 system images
Note that android-6 and android-7 are the same as android-5 for the NDK,
i.e. they provide exactly the same native ABIs!
diff --git a/docs/openmaxal/index.html b/docs/openmaxal/index.html
index cff4b5e..a1a853a 100644
--- a/docs/openmaxal/index.html
+++ b/docs/openmaxal/index.html
@@ -208,7 +208,7 @@
(see "Android extensions" below).
<p>
The source data format must be <code>XADataFormat_MIME</code>.
-Initialize <code>mimeType</code> to the UTF-8 string <code>"video/mp2ts"</code>,
+Initialize <code>mimeType</code> to <code>XA_ANDROID_MIME_MP2TS</code>,
and <code>containerType</code> to <code>XA_CONTAINERTYPE_MPEG_TS</code>.
<p>
The contained transport stream must have a single program with one H.264
@@ -223,18 +223,40 @@
<h4>StreamInformation</h4>
+Use the StreamInformation interface on a media player object to discover
+when the video metrics (height/width or aspect ratio) are available or
+changed, and to then get the sizes.
+<p>
+
Supported:
<ul>
-<li>Video size available or changed notification
-<li>Get video size (height/width and aspect ratio)
+<li><code>RegisterStreamChangeCallback</code>
+<li><code>QueryMediaContainerInformation</code>
+<li><code>QueryStreamInformation</code>
+<li><code>QueryStreamType</code>
</ul>
Not supported:
<ul>
+<li><code>QueryActiveStreams</code>
<li><code>QueryStreamName</code>
<li><code>SetActiveStream</code>
</ul>
+<h4>VideoDecoderCapabilities</h4>
+
+This interface on the engine object reports video decoder capabilities
+without interpretation, exactly as claimed by the underlying OpenMAX IL
+implementation.
+<p>
+These fields in <code>XAVideoCodecDescriptor</code> are filled:
+<ul>
+<li><code>codecId</code>
+<li><code>profileSetting</code>
+<li><code>levelSetting</code>
+</ul>
+The other fields are not filled and should be ignored.
+
<h3>Data structures</h3>
Android API level 14 supports these OpenMAX AL 1.0.1 data structures:
@@ -249,6 +271,7 @@
<li>XAMediaContainerInformation
<li>XANativeHandle
<li>XA*StreamInformation
+<li>XAVideoCodecDescriptor
</ul>
<h4>XADataLocator_NativeDisplay</h4>
@@ -429,10 +452,18 @@
<li>The completion callback receives additional parameters:
buffer address, buffer maximum data size, buffer actual size consumed (or filled by a future
recorder object), and a <code>void *</code> for application.
+<li>The callback returns a value, which must be <code>XA_RESULT_SUCCESS</code>.
</ul>
+The data locator type code is <code>XA_DATALOCATOR_ANDROIDBUFFERQUEUE</code> and
+the associated structure is <code>XADataLocator_AndroidBufferQueue</code>.
+<p>
+The interface ID is <code>XA_IID_ANDROIDBUFFERQUEUESOURCE</code>.
+
<h4>Usage</h4>
+A typical buffer queue configuration is 8 buffers of 1880 bytes each.
+<p>
The application enqueues filled buffers of data in MPEG-2 transport
stream format. The buffer size must be a multiple of 188 bytes,
the size of an MPEG-2 transport stream packet. The buffer data must
@@ -443,8 +474,11 @@
(command key/value pairs) at <code>Enqueue</code>:
<dl>
<dt>XA_ANDROID_ITEMKEY_EOS</dt>
-<dd>End of stream. The application does not intend to call <code>Enqueue</code> again.
-There is no associated value, so <code>itemSize</code> must be zero.</dd>
+<dd>End of stream. Informs the decode and rendering components that playback is complete.
+The application must not call <code>Enqueue</code> again.
+There is no associated value, so <code>itemSize</code> must be zero.
+There must be no data buffer alongside the EOS command.
+</dd>
<dt>XA_ANDROID_ITEMKEY_DISCONTINUITY</dt>
<dd>Discontinuity. This and following buffers have a new presentation time.
The new presentation time may be optionally specified as a parameter,
@@ -453,9 +487,16 @@
The discontinuity command is intended for seeking to a new point in
the stream. The application should flush its internal data, then send
the discontinuity command prior to, or alongside of, the first buffer
-corresponding to the new stream position. Note that the discontinuity
+corresponding to the new stream position.
+The initial packets in the video elementary stream
+should describe an IDR (Instantaneous Decoding Refresh) frame.
+Note that the discontinuity
command is not intended for stream configuration / format changes;
-these are not presently supported.
+for these use <code>XA_ANDROID_ITEMKEY_FORMAT_CHANGE</code>.
+</dd>
+<dt>XA_ANDROID_ITEMKEY_FORMAT_CHANGE</dt>
+<dd>Format change. This and following buffers have a new format,
+for example for MBR (Multiple Bit Rate) or resolution switching.
</dd>
</dl>
<p>
diff --git a/docs/opensles/index.html b/docs/opensles/index.html
index a1ea663..85dfb70 100644
--- a/docs/opensles/index.html
+++ b/docs/opensles/index.html
@@ -332,7 +332,8 @@
<h4>Seek</h4>
<code>SetLoop</code> enables whole file looping. The <code>startPos</code>
-and <code>endPos</code> parameters are ignored.
+parameter should be zero and the <code>endPos</code> parameter should
+be <code>SL_TIME_UNKNOWN</code>.
<h4>URI data locator</h4>
@@ -714,8 +715,8 @@
<p>
It is not recommended to starve the decoder by failing to provide full
ADTS AAC buffers, e.g. by returning from the Android buffer queue callback
-without enqueueing another full buffer. The result of starvation is
-decoder starvation is unspecified.
+without enqueueing another full buffer. The result of decoder starvation
+is unspecified.
<p>
In all respects except for the data source, the streaming decode method is similar
to that of the previous section:
@@ -748,7 +749,7 @@
<p>
The metadata key indices are available immediately after
<code>Object::Realize</code>. Yet the associated values are not
-available after the first encoded data has been decoded. A good
+available until after the first encoded data has been decoded. A good
practice is to query for the key indices in the main thread after Realize,
and to read the PCM format metadata values in the Android simple
buffer queue callback handler the first time it is called.
