1/*
2 * Copyright (C) 2016 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17package android.hardware.media.omx@1.0;
18
19import IOmxBufferSource;
20
21import android.hardware.media@1.0::types;
22
23/**
24 * Ref: frameworks/av/include/media/IOMX.h: IOMXNode
25 * Ref: https://www.khronos.org/registry/omxil/specs/OpenMAX_IL_1_1_2_Specification.pdf
26 */
27
28/**
29 * IOmxNode is an interface for communicating with an OMX component (called
30 * "node" here) that has been previously obtained by calling
31 * IOmx::allocateNode().
32 */
33interface IOmxNode {
34
35    /**
36     * Free the node.
37     *
38     * @return status Status of the call.
39     */
40    freeNode(
41        ) generates (
42            Status status
43        );
44
45    /**
46     * Invoke a command on the node.
47     *
48     * @param cmd Type of the command.
49     * @param param Parameter for the command.
50     * @return status Status of the call.
51     *
52     * @see OMX_SendCommand() in the OpenMax IL standard.
53     */
54    sendCommand(
55            uint32_t cmd,
56            int32_t param
57        ) generates (
58            Status status
59        );
60
61    /**
62     * Retrieve a parameter setting from the node.
63     *
64     * @param index Type of the parameter to retrieve.
65     * @param inParams Information about the retrieval.
66     * @return status Status of the call.
67     * @return outParams Current parameter setting.
68     *
69     * @see OMX_GetParameter() in the OpenMax IL standard.
70     */
71    getParameter(
72            uint32_t index,
73            Bytes inParams
74        ) generates (
75            Status status,
76            Bytes outParams
77        );
78
79    /**
80     * Change a parameter setting of the node.
81     *
82     * @param index Type of the parameter to change.
83     * @param params New parameter setting.
84     * @return status Status of the call.
85     *
86     * @see OMX_SetParameter() in the OpenMax IL standard.
87     */
88    setParameter(
89            uint32_t index,
90            Bytes params
91        ) generates (
92            Status status
93        );
94
95    /**
96     * Retrieve a configuration from the node.
97     *
98     * @param index Type of the configuration to retrieve.
99     * @param inConfig Information about the retrieval.
100     * @return status Status of the call.
101     * @return outConfig Current configuration.
102     *
103     * @see OMX_GetConfig() in the OpenMax IL standard.
104     */
105    getConfig(
106            uint32_t index,
107            Bytes inConfig
108        ) generates (
109            Status status,
110            Bytes outConfig
111        );
112
113    /**
114     * Change a configuration of the node.
115     *
116     * @param index Type of the configuration to change.
117     * @param config New configuration.
118     * @return status Status of the call.
119     *
120     * @see OMX_SetConfig() in the OpenMax IL standard.
121     */
122    setConfig(
123            uint32_t index,
124            Bytes config
125        ) generates (
126            Status status
127        );
128
129    /**
130     * Set the mode of a port on the node.
131     *
132     * @param portIndex Index of the port.
133     * @param mode Target mode on the specified port.
134     * @return status Status of the call.
135     */
136    setPortMode(
137            uint32_t portIndex,
138            PortMode mode
139        ) generates (
140            Status status
141        );
142
143    /**
144     * Prepare a port for adaptive playback. This is based on the extension
145     * "OMX.google.android.index.prepareForAdaptivePlayback".
146     *
147     * @param portIndex Index of the port.
148     * @param enable Whether the adaptive playback is enabled or not.
149     * @param maxFrameWidth Maximum frame width.
150     * @param maxFrameHeight Maximum frame height.
151     * @return status Status of the call.
152     */
153    prepareForAdaptivePlayback(
154            uint32_t portIndex,
155            bool enable,
156            uint32_t maxFrameWidth,
157            uint32_t maxFrameHeight
158        ) generates (
159            Status status
160        );
161
162    /**
163     * Configure a port for a tunneled playback mode. This is based on the
164     * extension "OMX.google.android.index.configureVideoTunnelMode".
165     *
166     * @param portIndex Index of the port.
167     * @param tunneled Whether the tunneled mode is used or not.
168     * @param audioHwSync HW SYNC ID of the audio HAL output stream to sync
169     * the video with.
170     * @return status Status of the call.
171     * @return sidebandHandle Codec-allocated sideband window handle.
172     */
173    configureVideoTunnelMode(
174            uint32_t portIndex,
175            bool tunneled,
176            uint32_t audioHwSync
177        ) generates (
178            Status status,
179            handle sidebandHandle
180        );
181
182    /**
183     * Retrieve the buffer usage on a port. This is based on the extension
184     * "OMX.google.android.index.getAndroidNativeBufferUsage".
185     *
186     * @param portIndex Index of the port.
187     * @return status Status of the call.
188     * @return usage Current graphic buffer usage.
189     */
190    getGraphicBufferUsage(
191            uint32_t portIndex
192        ) generates (
193            Status status,
194            uint32_t usage
195        );
196
197    /**
198     * Set up a listener to events related to the input surface.
199     *
200     * @param bufferSource Listener object that implements
201     * IOmxBufferSource.
202     * @return status Status of the call.
203     *
204     * @see IOmxBufferSource.
205     */
206    setInputSurface(
207            IOmxBufferSource bufferSource
208        ) generates (
209            Status status
210        );
211
212    /**
213     * Allocate an opaque buffer on a port as a native handle.
214     *
215     * @param portIndex Index of the port.
216     * @param size Desired size of the buffer.
217     * @return status Status of the call.
218     * @return buffer Id of the allocated buffer, which will be needed in
219     * other buffer-related functions.
220     * @return nativeHandle Native handle of the allocated buffer.
221     *
222     * @see OMX_AllocateBuffer() in the OpenMax IL standard.
223     */
224    allocateSecureBuffer(
225            uint32_t portIndex,
226            uint64_t size
227        ) generates (
228            Status status,
229            BufferId buffer,
230            handle nativeHandle
231        );
232
233    /**
234     * Assign a buffer to a port.
235     *
236     * @param portIndex Index of the port.
237     * @param omxBuffer Buffer to be assigned to the port.
238     * @return status Status of the call.
239     * @return buffer Id of the assigned buffer, which will be needed in
240     * other buffer-related functions.
241     *
242     * @see OMX_UseBuffer() in the OpenMax IL standard.
243     */
244    useBuffer(
245            uint32_t portIndex,
246            CodecBuffer omxBuffer
247        ) generates (
248            Status status,
249            BufferId buffer
250        );
251
252    /**
253     * Free a buffer previously assigned to a port by allocateSecureBuffer() or
254     * useBuffer().
255     *
256     * @param portIndex Index of the port.
257     * @param buffer Id of the buffer to be freed.
258     * @return status Status of the call.
259     *
260     * @see OMX_FreeBuffer() in the OpenMax IL standard.
261     */
262    freeBuffer(
263            uint32_t portIndex,
264            BufferId buffer
265        ) generates (
266            Status status
267        );
268
269    /**
270     * Pass \p fence to the node if it supports fences. Otherwise, it waits on
271     * \p fence before calling OMX_FillThisBuffer(). The node will take
272     * ownership of the fence even if this call fails.
273     *
274     * If the port is in metadata mode, the buffer will be updated to point to
275     * the new buffer passed in via \p omxBuffer before OMX_FillThisBuffer() is
276     * called. Otherwise, \p omxBuffer is not used.
277     *
278     * @param buffer Id of the buffer to fill.
279     * @param omxBuffer New buffer information (in metadata mode).
280     * @param fence Fence to wait for (if not null).
281     * @return status Status of the call.
282     *
283     * @see OMX_FillThisBuffer() in the OpenMax IL standard.
284     */
285    fillBuffer(
286            BufferId buffer,
287            CodecBuffer omxBuffer,
288            Fence fence
289        ) generates (
290            Status status
291        );
292
293    /**
294     * Pass \p fence to the node if it supports fences. Otherwise, wait on
295     * \p fence before calling OMX_EmptyThisBuffer(). The node will take
296     * ownership of the fence even if this call fails.
297     *
298     * If the port is in metadata mode, the buffer will be updated to point to
299     * the new buffer passed in via \p omxBuffer before OMX_EmptyThisBuffer() is
300     * called. Otherwise, \p omxBuffer is not used.
301     *
302     * @param buffer Id of the buffer to fill.
303     * @param omxBuffer New buffer information (in metadata mode).
304     * @param flags Flags to be passed to OMX_EmptyBuffer().
305     * @param timestampUs Timestamp OMX_EmptyBuffer().
306     * @param fence Fence to wait for (if not null).
307     * @return status Status of the call.
308     *
309     * @see OMX_EmptyThisBuffer() in the OpenMax IL standard.
310     */
311    emptyBuffer(
312            BufferId buffer,
313            CodecBuffer omxBuffer,
314            uint32_t flags,
315            uint64_t timestampUs,
316            Fence fence
317        ) generates (
318            Status status
319        );
320
321    /**
322     * Request the node to translate an extension string to an index.
323     *
324     * @param parameterName Requested extension string.
325     * @return status Status of the call.
326     * @return index Translated index.
327     *
328     * @see OMX_GetExtensionIndex() in the OpenMax IL standard.
329     */
330    getExtensionIndex(
331            string parameterName
332        ) generates (
333            Status status,
334            uint32_t index
335        );
336
337    /**
338     * Add an OMX message on the node's message queue. The instance of
339     * IOmxObserver that was obtained during the creation of the node will
340     * receive the message in batches by the callback
341     * IOmxObserver::onMessages().
342     *
343     * @param msg Message to send.
344     * @return status Status of the call.
345     *
346     * @see IOmxObserver::onMessages().
347     */
348    dispatchMessage(
349            Message msg
350        ) generates (
351            Status status
352        );
353};
354
355