/*
 * Copyright (C) 2016 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.camera.device@1.0;

import android.hardware.camera.common@1.0::types;
import android.hardware.graphics.common@1.0::types;

/**
 * Camera device HAL@1.0 preview stream operation interface.
 */
interface ICameraDevicePreviewCallback {

    /**
     * Acquire a buffer to write a preview buffer into.
     *
     * @return status The status code for this operation. If not OK, then
     *     buffer and stride must not be used.
     * @return bufferId A unique ID for the returned buffer.
     * @return buffer A handle to the buffer to write into. Must be non-null if the bufferId has not
     *     been seen by HAL before. Must be null if the bufferId is seen before. HAL must keep track
     *     of the bufferId to actual buffer handle mapping.
     * @return stride The stride between two rows of pixels in this buffer.
     */
    dequeueBuffer() generates (Status status, uint64_t bufferId, handle buffer, uint32_t stride);

    /**
     * Send a filled preview buffer to its consumer.
     *
     * @param bufferId The bufferId of the preview buffer
     * @return status The status code for this operation.
     */
    enqueueBuffer(uint64_t bufferId) generates (Status status);

    /**
     * Return a preview buffer unfilled. This buffer must not be sent on to the
     * preview consumer as a valid buffer, but may be reused as if it were
     * empty.
     *
     * @param bufferId The bufferId of the preview buffer
     * @return status The status code for this operation.
     */
    cancelBuffer(uint64_t bufferId) generates (Status status);

    /**
     * Set the number of preview buffers needed by the HAL.
     *
     * @param count The maximum number of preview buffers to allocate.
     * @return status The status code for this operation.
     */
    setBufferCount(uint32_t count) generates (Status status);

    /**
     * Set the dimensions and format of future preview buffers.
     *
     * The next buffer that is dequeued must match the requested size and
     * format.
     *
     * @return Status The status code for this operation.
     */
    setBuffersGeometry(uint32_t w, uint32_t h,
            android.hardware.graphics.common@1.0::PixelFormat format)
            generates (Status status);

    /**
     * Set the valid region of image data for the next buffer(s) to be enqueued.
     *
     * @return Status The status code for this operation.
     */
    setCrop(int32_t left, int32_t top, int32_t right, int32_t bottom)
            generates (Status status);

    /**
     * Set the producer usage flags for the next buffer(s) to be enqueued.
     *
     * @return Status The status code for this operation.
     */
    setUsage(BufferUsage usage) generates (Status status);

    /**
     * Set the expected buffering mode for the preview output.
     */
    setSwapInterval(int32_t interval) generates (Status status);

    /**
     * Get the minimum number of buffers the preview consumer endpoint needs
     * to hold for correct operation.
     *
     * @return Status The status code for this operation.
     * @return count The number of buffers the consumer has requested.
     */
    getMinUndequeuedBufferCount() generates (Status status, uint32_t count);

    /**
     * Set the timestamp for the next buffer to enqueue
     *
     * Timestamps are measured in nanoseconds, and must be comparable
     * and monotonically increasing between two frames in the same
     * preview stream. They do not need to be comparable between
     * consecutive or parallel preview streams, cameras, or app runs.
     *
     * @param timestamp The timestamp to set for future buffers.
     * @return Status The status code for this operation.
     */
    setTimestamp(int64_t timestamp) generates (Status status);

};