/*
 * 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.graphics.mapper@2.0;

import android.hardware.graphics.common@1.0;

interface IMapper {
    struct BufferDescriptorInfo {
        /**
         * The width specifies how many columns of pixels must be in the
         * allocated buffer, but does not necessarily represent the offset in
         * columns between the same column in adjacent rows. The rows may be
         * padded.
         */
        uint32_t width;

       /**
        * The height specifies how many rows of pixels must be in the
        * allocated buffer.
        */
        uint32_t height;

       /**
        * The number of image layers that must be in the allocated buffer.
        */
        uint32_t layerCount;

        /** Buffer pixel format. */
        PixelFormat format;

        /**
         * Buffer usage mask; valid flags can be found in the definition of
         * BufferUsage.
         */
        bitfield<BufferUsage> usage;
    };

    struct Rect {
        int32_t left;
        int32_t top;
        int32_t width;
        int32_t height;
    };

    /**
     * Creates a buffer descriptor. The descriptor can be used with IAllocator
     * to allocate buffers.
     *
     * Since the buffer descriptor fully describes a buffer, any device
     * dependent or device independent checks must be performed here whenever
     * possible. Specifically, when layered buffers are not supported, this
     * function must return UNSUPPORTED if layerCount is great than 1.
     *
     * @param descriptorInfo specifies the attributes of the descriptor.
     * @return error is NONE upon success. Otherwise,
     *                  BAD_VALUE when any of the specified attributes is
     *                            invalid or conflicting.
     *                  NO_RESOURCES when the creation cannot be fullfilled at
     *                               this time.
     *                  UNSUPPORTED when any of the specified attributes is
     *                              not supported.
     * @return descriptor is the newly created buffer descriptor.
     */
    @entry
    @callflow(next="*")
    createDescriptor(BufferDescriptorInfo descriptorInfo)
          generates (Error error,
                     BufferDescriptor descriptor);

    /**
     * Imports a raw buffer handle to create an imported buffer handle for use
     * with the rest of the mapper or with other in-process libraries.
     *
     * A buffer handle is considered raw when it is cloned (e.g., with
     * native_handle_clone) from another buffer handle locally, or when it is
     * received from another HAL server/client or another process. A raw
     * buffer handle must not be used to access the underlying graphics
     * buffer. It must be imported to create an imported handle first.
     *
     * This function must at least validate the raw handle before creating the
     * imported handle. It must also support importing the same raw handle
     * multiple times to create multiple imported handles. The imported handle
     * must be considered valid everywhere in the process, including in
     * another instance of the mapper.
     *
     * Because of passthrough HALs, a raw buffer handle received from a HAL
     * may actually have been imported in the process. importBuffer must treat
     * such a handle as if it is raw and must not return BAD_BUFFER. The
     * returned handle is independent from the input handle as usual, and
     * freeBuffer must be called on it when it is no longer needed.
     *
     * @param rawHandle is the raw buffer handle to import.
     * @return error is NONE upon success. Otherwise,
     *                  BAD_BUFFER when the raw handle is invalid.
     *                  NO_RESOURCES when the raw handle cannot be imported at
     *                               this time.
     * @return buffer is the imported buffer handle and has the type
     *         buffer_handle_t.
     */
    @entry
    @callflow(next="*")
    importBuffer(handle rawHandle) generates (Error error, pointer buffer);

    /**
     * Frees a buffer handle. Buffer handles returned by importBuffer must be
     * freed with this function when no longer needed.
     *
     * This function must free up all resources allocated by importBuffer for
     * the imported handle. For example, if the imported handle was created
     * with native_handle_create, this function must call native_handle_close
     * and native_handle_delete.
     *
     * @return error is NONE upon success. Otherwise,
     *                  BAD_BUFFER when the buffer is invalid.
     */
    @exit
    @callflow(next="*")
    freeBuffer(pointer buffer) generates (Error error);

    /**
     * Locks the given buffer for the specified CPU usage.
     *
     * Locking the same buffer simultaneously from multiple threads is
     * permitted, but if any of the threads attempt to lock the buffer for
     * writing, the behavior is undefined, except that it must not cause
     * process termination or block the client indefinitely. Leaving the
     * buffer content in an indeterminate state or returning an error are both
     * acceptable.
     *
     * The client must not modify the content of the buffer outside of
     * accessRegion, and the device need not guarantee that content outside of
     * accessRegion is valid for reading. The result of reading or writing
     * outside of accessRegion is undefined, except that it must not cause
     * process termination.
     *
     * An accessRegion of all-zeros means the entire buffer. That is, it is
     * equivalent to '(0,0)-(buffer width, buffer height)'.
     *
     * data will be filled with a pointer to the locked buffer memory. This
     * address will represent the top-left corner of the entire buffer, even
     * if accessRegion does not begin at the top-left corner.
     *
     * @param buffer is the buffer to lock.
     * @param cpuUsage specifies one or more CPU usage flags to request.
     * @param accessRegion is the portion of the buffer that the client
     *        intends to access.
     * @param acquireFence when non-empty, is a handle containing a file
     *        descriptor referring to a sync fence object, which will be
     *        signaled when it is safe for the mapper to lock the buffer. If
     *        it is already safe to lock, acquireFence is empty.
     * @return error is NONE upon success. Otherwise,
     *                  BAD_BUFFER when the buffer is invalid or is
     *                             incompatible with this function.
     *                  BAD_VALUE when cpuUsage is 0, contains non-CPU usage
     *                            flags, or is incompatible with the buffer.
     *                  NO_RESOURCES when the buffer cannot be locked at this
     *                               time, but locking may succeed at a future
     *                               time.
     * @return data is a CPU-accessible pointer to the buffer data.
     */
    @callflow(next="unlock")
    lock(pointer buffer,
         bitfield<BufferUsage> cpuUsage,
         Rect accessRegion,
         handle acquireFence)
        generates (Error error,
                   pointer data);

    /**
     * This is largely the same as lock(), except that instead of returning a
     * pointer directly to the buffer data, it returns an YCbCrLayout struct
     * describing how to access the data planes.
     *
     * This function must work on buffers with PixelFormat::YCbCr_*_888 if
     * supported by the device, as well as with any other formats requested by
     * multimedia codecs when they are configured with a
     * flexible-YUV-compatible color format.
     *
     * @param buffer is the buffer to lock.
     * @param cpuUsage specifies one or more CPU usage flags to request.
     * @param accessRegion is the portion of the buffer that the client
     *        intends to access.
     * @param acquireFence when non-empty, is a handle containing a file
     *        descriptor referring to a sync fence object, which will be
     *        signaled when it is safe for the mapper to lock the buffer. If
     *        it is already safe to lock, acquireFence is empty.
     * @return error is NONE upon success. Otherwise,
     *                  BAD_BUFFER when the buffer is invalid or is
     *                             incompatible with this function.
     *                  BAD_VALUE when cpuUsage is 0, contains non-CPU usage
     *                            flags, or is incompatible with the buffer.
     *                  NO_RESOURCES when the buffer cannot be locked at this
     *                               time, but locking may succeed at a future
     *                               time.
     * @return layout is the data layout of the buffer.
     */
    @callflow(next="unlock")
    lockYCbCr(pointer buffer,
              bitfield<BufferUsage> cpuUsage,
              Rect accessRegion,
              handle acquireFence)
        generates (Error error,
                   YCbCrLayout layout);

    /**
     * Unlocks a buffer to indicate all CPU accesses to the buffer have
     * completed.
     *
     * @param buffer is the buffer to unlock.
     * @return error is NONE upon success. Otherwise,
     *                  BAD_BUFFER when the buffer is invalid or not locked.
     * @return releaseFence, when non-empty, is a handle containing a file
     *         descriptor referring to a sync fence object. The sync fence
     *         object will be signaled when the mapper has completed any
     *         pending work.
     */
    @callflow(next="*")
    unlock(pointer buffer)
        generates (Error error,
                   handle releaseFence);
};