1/*
2 * Copyright (C) 2018 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.c2@1.0;
18
19import android.hardware.graphics.bufferqueue@1.0::IGraphicBufferProducer;
20import android.hardware.graphics.bufferqueue@2.0::IGraphicBufferProducer;
21import android.hardware.media.omx@1.0::IGraphicBufferSource;
22
23import IConfigurable;
24import IComponentInterface;
25import IComponentListener;
26import IInputSink;
27import IInputSurface;
28import IInputSurfaceConnection;
29
30/**
31 * Interface for a Codec2 component corresponding to API level 1.0 or below.
32 * Components have two states: stopped and running. The running state has three
33 * sub-states: executing, tripped and error.
34 *
35 * All methods in `IComponent` must not block. If a method call cannot be
36 * completed in a timely manner, it must return `TIMED_OUT` in the return
37 * status.
38 */
39interface IComponent {
40
41    // METHODS AVAILABLE WHEN RUNNING
42    // =========================================================================
43
44    /**
45     * Queues up work for the component.
46     *
47     * This method must be supported in running (including tripped) states.
48     *
49     * It is acceptable for this method to return `OK` and return an error value
50     * using the IComponentListener::onWorkDone() callback.
51     *
52     * @param workBundle `WorkBundle` object containing a list of `Work` objects
53     *     to queue to the component.
54     * @return status Status of the call, which may be
55     *   - `OK`        - Works in @p workBundle were successfully queued.
56     *   - `BAD_INDEX` - Some component id in some `Worklet` is not valid.
57     *   - `CANNOT_DO` - The components are not tunneled but some `Work` object
58     *                   contains tunneling information.
59     *   - `NO_MEMORY` - Not enough memory to queue @p workBundle.
60     *   - `TIMED_OUT` - The operation cannot be finished in a timely manner.
61     *   - `CORRUPTED` - Some unknown error occurred.
62     */
63    queue(WorkBundle workBundle) generates (Status status);
64
65    /**
66     * Discards and abandons any pending `Work` items for the component.
67     *
68     * This method must be supported in running (including tripped) states.
69     *
70     * `Work` that could be immediately abandoned/discarded must be returned in
71     * @p flushedWorkBundle. The order in which queued `Work` items are
72     * discarded can be arbitrary.
73     *
74     * `Work` that could not be abandoned or discarded immediately must be
75     * marked to be discarded at the earliest opportunity, and must be returned
76     * via IComponentListener::onWorkDone(). This must be completed within
77     * 500ms.
78     *
79     * @return status Status of the call, which may be
80     *   - `OK`        - The component has been successfully flushed.
81     *   - `TIMED_OUT` - The operation cannot be finished in a timely manner.
82     *   - `CORRUPTED` - Some unknown error occurred.
83     * @return flushedWorkBundle `WorkBundle` object containing flushed `Work`
84     *     items.
85     */
86    flush(
87        ) generates (
88            Status status,
89            WorkBundle flushedWorkBundle
90        );
91
92    /**
93     * Drains the component, and optionally downstream components. This is a
94     * signalling method; as such it does not wait for any work completion.
95     *
96     * The last `Work` item is marked as "drain-till-here", so the component is
97     * notified not to wait for further `Work` before it processes what is
98     * already queued. This method can also be used to set the end-of-stream
99     * flag after `Work` has been queued. Client can continue to queue further
100     * `Work` immediately after this method returns.
101     *
102     * This method must be supported in running (including tripped) states.
103     *
104     * `Work` that is completed must be returned via
105     * IComponentListener::onWorkDone().
106     *
107     * @param withEos Whether to drain the component with marking end-of-stream.
108     * @return status Status of the call, which may be
109     *   - `OK`        - The drain request has been successfully recorded.
110     *   - `TIMED_OUT` - The operation cannot be finished in a timely manner.
111     *   - `CORRUPTED` - Some unknown error occurred.
112     */
113    drain(bool withEos) generates (Status status);
114
115    /**
116     * Starts using a surface for output.
117     *
118     * This method must not block.
119     *
120     * @param blockPoolId Id of the `C2BlockPool` to be associated with the
121     *     output surface.
122     * @param surface Output surface.
123     * @return status Status of the call, which may be
124     *   - `OK`        - The operation completed successfully.
125     *   - `CANNOT_DO` - The component does not support an output surface.
126     *   - `REFUSED`   - The output surface cannot be accessed.
127     *   - `TIMED_OUT` - The operation cannot be finished in a timely manner.
128     *   - `CORRUPTED` - Some unknown error occurred.
129     */
130    setOutputSurface(
131            uint64_t blockPoolId,
132            @2.0::IGraphicBufferProducer surface
133        ) generates (
134            Status status
135        );
136
137    /**
138     * Starts using an input surface.
139     *
140     * The component must be in running state.
141     *
142     * @param inputSurface Input surface to connect to.
143     * @return status Status of the call, which may be
144     *   - `OK`        - The operation completed successfully.
145     *   - `CANNOT_DO` - The component does not support an input surface.
146     *   - `BAD_STATE` - The component is not in running state.
147     *   - `DUPLICATE` - The component is already connected to an input surface.
148     *   - `REFUSED`   - The input surface is already in use.
149     *   - `NO_MEMORY` - Not enough memory to start the component.
150     *   - `TIMED_OUT` - The operation cannot be finished in a timely manner.
151     *   - `CORRUPTED` - Some unknown error occurred.
152     * @return connection `IInputSurfaceConnection` object, which can be used to
153     *     query and configure properties of the connection. This cannot be
154     *     null.
155     */
156    connectToInputSurface(
157            IInputSurface inputSurface
158        ) generates (
159            Status status,
160            IInputSurfaceConnection connection
161        );
162
163    /**
164     * Starts using an OMX input surface.
165     *
166     * The component must be in running state.
167     *
168     * This method is similar to connectToInputSurface(), but it takes an OMX
169     * input surface (as a pair of `IGraphicBufferProducer` and
170     * `IGraphicBufferSource`) instead of Codec2's own `IInputSurface`.
171     *
172     * @param producer Producer component of an OMX input surface.
173     * @param source Source component of an OMX input surface.
174     * @return status Status of the call, which may be
175     *   - `OK`        - The operation completed successfully.
176     *   - `CANNOT_DO` - The component does not support an OMX input surface.
177     *   - `BAD_STATE` - The component is not in running state.
178     *   - `DUPLICATE` - The component is already connected to an input surface.
179     *   - `REFUSED`   - The input surface is already in use.
180     *   - `NO_MEMORY` - Not enough memory to start the component.
181     *   - `TIMED_OUT` - The operation cannot be finished in a timely manner.
182     *   - `CORRUPTED` - Some unknown error occurred.
183     * @return connection `IInputSurfaceConnection` object, which can be used to
184     *     query and configure properties of the connection. This cannot be
185     *     null.
186     */
187    connectToOmxInputSurface(
188            @1.0::IGraphicBufferProducer producer,
189            IGraphicBufferSource source
190        ) generates (
191            Status status,
192            IInputSurfaceConnection connection
193        );
194
195    /**
196     * Stops using an input surface.
197     *
198     * The component must be in running state.
199     *
200     * @return status Status of the call, which may be
201     *   - `OK`        - The operation completed successfully.
202     *   - `CANNOT_DO` - The component does not support an input surface.
203     *   - `BAD_STATE` - The component is not in running state.
204     *   - `NOT_FOUND` - The component is not connected to an input surface.
205     *   - `TIMED_OUT` - The operation cannot be finished in a timely manner.
206     *   - `CORRUPTED` - Some unknown error occurred.
207     */
208    disconnectFromInputSurface() generates (Status Status);
209
210    /**
211     * Creates a local `C2BlockPool` backed by the given allocator and returns
212     * its id.
213     *
214     * The returned @p blockPoolId is the only way the client can refer to a
215     * `C2BlockPool` object in the component. The id can be passed to
216     * setOutputSurface() or used in some C2Param objects later.
217     *
218     * The created `C2BlockPool` object can be destroyed by calling
219     * destroyBlockPool(), reset() or release(). reset() and release() must
220     * destroy all `C2BlockPool` objects that have been created.
221     *
222     * @param allocatorId Id of a `C2Allocator`.
223     * @return status Status of the call, which may be
224     *   - `OK`        - The operation completed successfully.
225     *   - `NO_MEMORY` - Not enough memory to create the pool.
226     *   - `BAD_VALUE` - @p allocatorId is not recognized.
227     *   - `TIMED_OUT` - The operation cannot be finished in a timely manner.
228     *   - `CORRUPTED` - Some unknown error occurred.
229     * @return blockPoolId Id of the created C2BlockPool object. This may be
230     *     used in setOutputSurface() if the allocator
231     * @return configurable Configuration interface for the created pool. This
232     *     must not be null.
233     */
234    createBlockPool(uint32_t allocatorId) generates (
235        Status status,
236        uint64_t blockPoolId,
237        IConfigurable configurable
238    );
239
240    /**
241     * Destroys a local block pool previously created by createBlockPool().
242     *
243     * @param blockPoolId Id of a `C2BlockPool` that was previously returned by
244     *      createBlockPool().
245     * @return status Status of the call, which may be
246     *   - `OK`        - The operation completed successfully.
247     *   - `NOT_FOUND` - The supplied blockPoolId is not valid.
248     *   - `TIMED_OUT` - The operation cannot be finished in a timely manner.
249     *   - `CORRUPTED` - Some unknown error occurred.
250     */
251    destroyBlockPool(uint64_t blockPoolId) generates (Status status);
252
253    // STATE CHANGE METHODS
254    // =========================================================================
255
256    /**
257     * Starts the component.
258     *
259     * This method must be supported in stopped state as well as tripped state.
260     *
261     * If the return value is `OK`, the component must be in the running state.
262     * If the return value is `BAD_STATE` or `DUPLICATE`, no state change is
263     * expected as a response to this call. Otherwise, the component must be in
264     * the stopped state.
265     *
266     * If a component is in the tripped state and start() is called while the
267     * component configuration still results in a trip, start() must succeed and
268     * a new onTripped() callback must be used to communicate the configuration
269     * conflict that results in the new trip.
270     *
271     * @return status Status of the call, which may be
272     *   - `OK`        - The component has started successfully.
273     *   - `BAD_STATE` - Component is not in stopped or tripped state.
274     *   - `DUPLICATE` - When called during another start call from another
275     *                   thread.
276     *   - `NO_MEMORY` - Not enough memory to start the component.
277     *   - `TIMED_OUT` - The operation cannot be finished in a timely manner.
278     *   - `CORRUPTED` - Some unknown error occurred.
279     */
280    start() generates (Status status);
281
282    /**
283     * Stops the component.
284     *
285     * This method must be supported in running (including tripped) state.
286     *
287     * This method must return withing 500ms.
288     *
289     * Upon this call, all pending `Work` must be abandoned.
290     *
291     * If the return value is `BAD_STATE` or `DUPLICATE`, no state change is
292     * expected as a response to this call. For all other return values, the
293     * component must be in the stopped state.
294     *
295     * This does not alter any settings and tunings that may have resulted in a
296     * tripped state.
297     *
298     * @return status Status of the call, which may be
299     *   - `OK`        - The component has stopped successfully.
300     *   - `BAD_STATE` - Component is not in running state.
301     *   - `DUPLICATE` - When called during another stop call from another
302     *                   thread.
303     *   - `TIMED_OUT` - The operation cannot be finished in a timely manner.
304     *   - `CORRUPTED` - Some unknown error occurred.
305     */
306    stop() generates (Status status);
307
308    /**
309     * Resets the component.
310     *
311     * This method must be supported in all (including tripped) states other
312     * than released.
313     *
314     * This method must be supported during any other blocking call.
315     *
316     * This method must return withing 500ms.
317     *
318     * When this call returns, if @p status is `OK`, all `Work` items must
319     * have been abandoned, and all resources (including `C2BlockPool` objects
320     * previously created by createBlockPool()) must have been released.
321     *
322     * If the return value is `BAD_STATE` or `DUPLICATE`, no state change is
323     * expected as a response to this call. For all other return values, the
324     * component must be in the stopped state.
325     *
326     * This brings settings back to their default, "guaranteeing" no tripped
327     * state.
328     *
329     * @return status Status of the call, which may be
330     *   - `OK`        - The component has been reset.
331     *   - `BAD_STATE` - Component is in released state.
332     *   - `DUPLICATE` - When called during another reset call from another
333     *                   thread.
334     *   - `TIMED_OUT` - The operation cannot be finished in a timely manner.
335     *   - `CORRUPTED` - Some unknown error occurred.
336     */
337    reset() generates (Status status);
338
339    /**
340     * Releases the component.
341     *
342     * This method must be supported in stopped state.
343     *
344     * This method destroys the component. Upon return, if @p status is `OK` or
345     * `DUPLICATE`, all resources must have been released.
346     *
347     * @return status Status of the call, which may be
348     *   - `OK`        - The component has been released.
349     *   - `BAD_STATE` - The component is running.
350     *   - `DUPLICATE` - The component is already released.
351     *   - `TIMED_OUT` - The operation cannot be finished in a timely manner.
352     *   - `CORRUPTED` - Some unknown error occurred.
353     */
354    release() generates (Status status);
355
356    /**
357     * Returns the @ref IComponentInterface instance associated to this
358     * component.
359     *
360     * An @ref IConfigurable instance for the component can be obtained by calling
361     * IComponentInterface::getConfigurable() on the returned @p intf.
362     *
363     * @return intf `IComponentInterface` instance. This must not be null.
364     */
365    getInterface() generates (IComponentInterface intf);
366
367    /**
368     * Returns an @ref IInputSink instance that has the component as the
369     * underlying implementation.
370     *
371     * @return sink `IInputSink` instance.
372     */
373    asInputSink() generates (IInputSink sink);
374};
375
376