1/*
2 * Copyright 2019 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.1;
18
19import android.hardware.media.c2@1.0::IComponent;
20import android.hardware.media.c2@1.0::Status;
21
22/**
23 * Interface for a Codec2 component corresponding to API level 1.0 or below.
24 * Components have two states: stopped and running. The running state has three
25 * sub-states: executing, tripped and error.
26 *
27 * All methods in `IComponent` must not block. If a method call cannot be
28 * completed in a timely manner, it must return `TIMED_OUT` in the return
29 * status.
30 *
31 * @note This is an extension of version 1.0 of `IComponent`. The purpose of the
32 * extension is to add support for tunneling.
33 */
34interface IComponent extends @1.0::IComponent {
35    /**
36      * Configures a component for a tunneled playback mode.
37      *
38      * A successful call to this method puts the component in the *tunneled*
39      * mode. In this mode, the output `Worklet`s returned in
40      * IComponentListener::onWorkDone() may not contain any buffers. The output
41      * buffers are passed directly to the consumer end of a buffer queue whose
42      * producer side is configured with the returned @p sidebandStream passed
43      * to IGraphicBufferProducer::setSidebandStream().
44      *
45      * The component is initially in the non-tunneled mode by default. The
46      * tunneled mode can be toggled on only before the component starts
47      * processing. Once the component is put into the tunneled mode, it shall
48      * stay in the tunneled mode until and only until reset() is called.
49      *
50      * @param avSyncHwId A resource ID for hardware sync. The generator of sync
51      *     IDs must ensure that this number is unique among all services at any
52      *     given time. For example, if both the audio HAL and the tuner HAL
53      *     support this feature, sync IDs from the audio HAL must not clash
54      *     with sync IDs from the tuner HAL.
55      * @return status Status of the call, which may be
56      *   - `OK`        - The operation completed successfully. In this case,
57      *                   @p sidebandHandle shall not be a null handle.
58      *   - `OMITTED`   - The component does not support video tunneling.
59      *   - `BAD_STATE` - The component is already running.
60      *   - `TIMED_OUT` - The operation cannot be finished in a timely manner.
61      *   - `CORRUPTED` - Some unknown error occurred.
62      * @return sidebandHandle Codec-allocated sideband stream handle. This can
63      *     be passed to IGraphicBufferProducer::setSidebandStream() to
64      *     establish a direct channel to the consumer.
65      */
66     configureVideoTunnel(
67             uint32_t avSyncHwId
68         ) generates (
69             Status status,
70             handle sidebandHandle
71         );
72};
73