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 hardware.google.media.c2@1.0;
18
19import android.hardware.graphics.bufferqueue@1.0::IGraphicBufferProducer;
20import android.hardware.media.omx@1.0::IGraphicBufferSource;
21
22import IConfigurable;
23import IComponentInterface;
24import IComponentListener;
25
26/**
27 * Interface for a Codec 2.0 component corresponding to API level 1.0 or
28 * below. Components have two states: stopped and running. The running
29 * state has three sub-states: executing, tripped and error.
30 */
31interface IComponent extends IComponentInterface {
32
33    // METHODS AVAILABLE WHEN RUNNING
34    // =========================================================================
35
36    /**
37     * Queues up work for the component.
38     *
39     * This method must be supported in running (including tripped) states.
40     *
41     * This method must return within 1ms
42     *
43     * It is acceptable for this method to return OK and return an error value
44     * using the onWorkDone() callback.
45     *
46     * @param workBundle WorkBundle object containing Works to queue to the
47     * component.
48     * @return status Status of the call, which may be
49     *   - OK        - Works in \p workBundle were successfully queued.
50     *   - BAD_INDEX - Some component(s) in some Work do(es) not exist.
51     *   - CANNOT_DO - The components are not tunneled.
52     *   - NO_MEMORY - Not enough memory to queue \p workBundle.
53     *   - CORRUPTED - Some unknown error prevented queuing the Works.
54     *                 (unexpected).
55     */
56    queue(WorkBundle workBundle) generates (Status status);
57
58    /**
59     * Discards and abandons any pending work for the component.
60     *
61     * This method must be supported in running (including tripped) states.
62     *
63     * This method must return within 5ms.
64     *
65     * Work that could be immediately abandoned/discarded must be returned in
66     * \p flushedWorks; this can be done in an arbitrary order.
67     *
68     * Work that could not be abandoned or discarded immediately must be marked
69     * to be discarded at the earliest opportunity, and must be returned via
70     * the onWorkDone() callback. This must be completed within 500ms.
71     *
72     * @return status Status of the call, which may be
73     *   - OK        - The component has been successfully flushed.
74     *   - TIMED_OUT - The flush could not be completed within the time limit.
75     *                 (unexpected)
76     *   - CORRUPTED - Some unknown error prevented flushing from
77     *                 completion. (unexpected)
78     * @return flushedWorkBundle WorkBundle object containing flushed Works.
79     */
80    flush(
81        ) generates (
82            Status status,
83            WorkBundle flushedWorkBundle
84        );
85
86    /**
87     * Drains the component, and optionally downstream components. This is a
88     * signalling method; as such it does not wait for any work completion.
89     *
90     * Marks last work item as "drain-till-here", so component is notified not
91     * to wait for further work before it processes work already queued. This
92     * method can also be used to set the end-of-stream flag after work has been
93     * queued. Client can continue to queue further work immediately after this
94     * method returns.
95     *
96     * This method must be supported in running (including tripped) states.
97     *
98     * This method must return within 1ms.
99     *
100     * Work that is completed must be returned via the onWorkDone() callback.
101     *
102     * @param withEos Whether to drain the component with marking end-of-stream.
103     * @return status Status of the call, which may be
104     *   - OK        - The drain request has been successfully recorded.
105     *   - TIMED_OUT - The flush could not be completed within the time limit.
106     *                 (unexpected)
107     *   - CORRUPTED - Some unknown error prevented flushing from completion.
108     *                 (unexpected)
109     */
110    drain(bool withEos) generates (Status status);
111
112    /**
113     * Starts using a surface for output.
114     *
115     * @param blockPoolId The id of the BlockPool to be associated with the
116     * output surface.
117     * @param surface A surface to use for codec output.
118     * @return status Status of the call, which may be
119     *   - OK        - The operation completed successfully.
120     *   - CANNOT_DO - The component does not support an output surface.
121     *   - REFUSED   - The output surface cannot be accessed.
122     *   - TIMED_OUT - The component could not be connected within the time
123     *                 limit. (unexpected)
124     *   - CORRUPTED - Some unknown error prevented connecting the component.
125     *                 (unexpected)
126     */
127    setOutputSurface(
128            uint64_t blockPoolId,
129            IGraphicBufferProducer surface
130        ) generates (
131            Status status
132        );
133
134    /**
135     * Starts using a persistent OMX input surface for a component.
136     *
137     * The component must be in running state.
138     *
139     * @param producer Producer component of an OMX persistent input surface.
140     * @param source Source component of an OMX persistent input surface.
141     * @return status Status of the call, which may be
142     *   - OK        - The operation completed successfully.
143     *   - CANNOT_DO - The component does not support an input surface.
144     *   - BAD_STATE - Component is not in running state.
145     *   - DUPLICATE - The component is already connected to an input surface.
146     *   - REFUSED   - The input surface is already in use.
147     *   - NO_MEMORY - Not enough memory to start the component.
148     *   - TIMED_OUT - The component could not be connected within the time
149     *                 limit. (unexpected)
150     *   - CORRUPTED - Some unknown error prevented connecting the component.
151     *                 (unexpected)
152     */
153    connectToOmxInputSurface(
154            IGraphicBufferProducer producer,
155            IGraphicBufferSource source
156        ) generates (Status status);
157
158    /**
159     * Stops using an input surface.
160     *
161     * This call is used for both Codec 2.0 and OMX input surfaces.
162     *
163     * The component must be in running state.
164     *
165     * @return status Status of the call, which may be
166     *   - OK        - The operation completed successfully.
167     *   - CANNOT_DO - The component does not support an input surface.
168     *   - BAD_STATE - Component is not in running state.
169     *   - NOT_FOUND - The component is not connected to an input surface.
170     *   - TIMED_OUT - The component could not be connected within the time
171     *                 limit. (unexpected)
172     *   - CORRUPTED - Some unknown error prevented connecting the component.
173     *                 (unexpected)
174     */
175    disconnectFromInputSurface() generates (Status Status);
176
177    /**
178     * Creates a local block pool backed by the given allocator and returns its
179     * identifier.
180     *
181     * This call must return within 100 msec.
182     *
183     * @param allocatorId The Codec 2.0 allocator ID
184     * @return status Status of the call, which may be
185     *   - OK        - The operation completed successfully.
186     *   - NO_MEMORY - Not enough memory to create the pool.
187     *   - BAD_VALUE - Invalid allocator.
188     *   - TIMED_OUT - The pool could not be created within the time
189     *                 limit. (unexpected)
190     *   - CORRUPTED - Some unknown error prevented creating the pool.
191     *                 (unexpected)
192     * @return blockPoolId The Codec 2.0 blockpool ID for the created pool.
193     * @return configurable Configuration interface for the created pool.
194     */
195    createBlockPool(uint32_t allocatorId) generates (
196        Status status,
197        uint64_t blockPoolId,
198        IConfigurable configurable
199    );
200
201    /**
202     * Destroys a local block pool previously created by createBlockPool().
203     *
204     * This call must return within 100 msec.
205     *
206     * @param blockPoolId The block pool id previously returned by
207     *      createBlockPool().
208     * @return status Status of the call, which may be
209     *   - OK        - The operation completed successfully.
210     *   - NOT_FOUND - The supplied blockPoolId is not valid.
211     *   - TIMED_OUT - The pool could not be destroyedwithin the time limit.
212     *                 (unexpected)
213     *   - CORRUPTED - Some unknown error prevented destruction of the pool.
214     *                 (unexpected)
215     */
216    destroyBlockPool(uint64_t blockPoolId) generates (Status status);
217
218    // STATE CHANGE METHODS
219    // =========================================================================
220
221    /**
222     * Starts the component.
223     *
224     * This method must be supported in stopped state as well as tripped state.
225     *
226     * If the return value is OK, the component must be in the running state.
227     * If the return value is BAD_STATE or DUPLICATE, no state change is
228     * expected as a response to this call.
229     * Otherwise, the component must be in the stopped state.
230     *
231     * If a component is in the tripped state and start() is called while the
232     * component configuration still results in a trip, start must succeed and
233     * a new onTripped callback must be used to communicate the configuration
234     * conflict that results in the new trip.
235     *
236     * This method must return within 500ms.
237     *
238     * @return status Status of the call, which may be
239     *   - OK        - The component has started successfully.
240     *   - BAD_STATE - Component is not in stopped or tripped state.
241     *   - DUPLICATE - When called during another start call from another
242     *                 thread.
243     *   - NO_MEMORY - Not enough memory to start the component.
244     *   - TIMED_OUT - The component could not be started within the time limit.
245     *                 (unexpected)
246     *   - CORRUPTED - Some unknown error prevented starting the component.
247     *                 (unexpected)
248     */
249    start() generates (Status status);
250
251    /**
252     * Stops the component.
253     *
254     * This method must be supported in running (including tripped) state.
255     *
256     * This method must return withing 500ms.
257     *
258     * Upon this call, all pending work must be abandoned.
259     * If the return value is BAD_STATE or DUPLICATE, no state change is
260     * expected as a response to this call.
261     * For all other return values, the component must be in the stopped state.
262     *
263     * This does not alter any settings and tunings that may have resulted in a
264     * tripped state.
265     *
266     * @return status Status of the call, which may be
267     *   - OK        - The component has stopped successfully.
268     *   - BAD_STATE - Component is not in running state.
269     *   - DUPLICATE - When called during another stop call from another thread.
270     *   - TIMED_OUT - The component could not be stopped within the time limit.
271     *                 (unexpected)
272     *   - CORRUPTED - Some unknown error prevented starting the component.
273     *                 (unexpected)
274     */
275    stop() generates (Status status);
276
277    /**
278     * Resets the component.
279     *
280     * This method must be supported in all (including tripped) states other
281     * than released.
282     *
283     * This method must be supported during any other blocking call.
284     *
285     * This method must return withing 500ms.
286     *
287     * After this call returns all work must have been abandoned, all references
288     * must have been released.
289     *
290     * If the return value is BAD_STATE or DUPLICATE, no state change is
291     * expected as a response to this call.
292     * For all other return values, the component shall be in the stopped state.
293     *
294     * This brings settings back to their default - "guaranteeing" no tripped
295     * state.
296     *
297     * @return status Status of the call, which may be
298     *   - OK        - The component has been reset.
299     *   - BAD_STATE - Component is in released state.
300     *   - DUPLICATE - When called during another reset call from another
301     *                 thread.
302     *   - TIMED_OUT - The component could not be reset within the time limit.
303     *                 (unexpected)
304     *   - CORRUPTED - Some unknown error prevented resetting the component.
305     *                 (unexpected)
306     */
307    reset() generates (Status status);
308
309    /**
310     * Releases the component.
311     *
312     * This method must be supported in stopped state.
313     *
314     * This method must return withing 500ms. Upon return all references must
315     * be abandoned.
316     *
317     * @return status Status of the call, which may be
318     *   - OK        - The component has been released.
319     *   - BAD_STATE - The component is running.
320     *   - DUPLICATE - The component is already released.
321     *   - TIMED_OUT - The component could not be released within the time
322     *                 limit. (unexpected)
323     *   - CORRUPTED - Some unknown error prevented releasing the component.
324     *                 (unexpected)
325     */
326    release() generates (Status status);
327
328};
329
330