/*
 * Copyright 2021 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package android.hardware.media.c2@1.2;

import android.hardware.graphics.bufferqueue@2.0::IGraphicBufferProducer;
import android.hardware.media.c2@1.1::IComponent;
import android.hardware.media.c2@1.0::Status;


/**
 * Interface for a Codec2 component corresponding to API level 1.2 or below.
 * Components have two states: stopped and running. The running state has three
 * sub-states: executing, tripped and error.
 *
 * All methods in `IComponent` must not block. If a method call cannot be
 * completed in a timely manner, it must return `TIMED_OUT` in the return
 * status.
 *
 * @note This is an extension of version 1.1 of `IComponent`. The purpose of the
 * extension is to add blocking allocation of output buffer from surface.
 */
interface IComponent extends @1.1::IComponent {
    /**
     * Starts using a surface for output with a synchronization object
     *
     * This method must not block.
     *
     * @param blockPoolId Id of the `C2BlockPool` to be associated with the
     *     output surface.
     * @param surface Output surface.
     * @param syncObject synchronization object for buffer allocation between
     *     Framework and Component.
     * @return status Status of the call, which may be
     *   - `OK`        - The operation completed successfully.
     *   - `CANNOT_DO` - The component does not support an output surface.
     *   - `REFUSED`   - The output surface cannot be accessed.
     *   - `TIMED_OUT` - The operation cannot be finished in a timely manner.
     *   - `CORRUPTED` - Some unknown error occurred.
     */
    setOutputSurfaceWithSyncObj(
            uint64_t blockPoolId,
            @2.0::IGraphicBufferProducer surface,
            SurfaceSyncObj syncObject
        ) generates (
            Status status
        );
};