/*
 * Copyright 2017 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.1;

import android.hardware.graphics.common@1.1::BufferUsage;
import android.hardware.graphics.common@1.1::PixelFormat;
import @2.0::BufferDescriptor;
import @2.0::Error;
import @2.0::IMapper;

interface IMapper extends @2.0::IMapper {
    /**
     * This is the same as @2.0::IMapper::BufferDescriptorInfo except that it
     * accepts @1.1::PixelFormat and @1.1::BufferUsage.
     */
    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;
    };

    /**
     * Validate that the buffer can be safely accessed by a caller who assumes
     * the specified descriptorInfo and stride. This must at least validate
     * that the buffer size is large enough. Validating the buffer against
     * individual buffer attributes is optional.
     *
     * @param buffer is the buffer to validate against.
     * @param descriptorInfo specifies the attributes of the buffer.
     * @param stride is the buffer stride returned by IAllocator::allocate.
     * @return error is NONE upon success. Otherwise,
     *                  BAD_BUFFER when the buffer is invalid.
     *                  BAD_VALUE when buffer cannot be safely accessed
     */
    validateBufferSize(pointer buffer,
                       BufferDescriptorInfo descriptorInfo,
                       uint32_t stride)
            generates (Error error);

    /**
     * Get the transport size of a buffer. An imported buffer handle is a raw
     * buffer handle with the process-local runtime data appended. This
     * function, for example, allows a caller to omit the process-local
     * runtime data at the tail when serializing the imported buffer handle.
     *
     * Note that a client might or might not omit the process-local runtime
     * data when sending an imported buffer handle. The mapper must support
     * both cases on the receiving end.
     *
     * @param buffer is the buffer to get the transport size from.
     * @return error is NONE upon success. Otherwise,
     *                  BAD_BUFFER when the buffer is invalid.
     * @return numFds is the number of file descriptors needed for transport.
     * @return numInts is the number of integers needed for transport.
     */
    getTransportSize(pointer buffer)
            generates (Error error,
                       uint32_t numFds,
                       uint32_t numInts);

    /**
     * This is the same as @2.0::IMapper::createDescriptor except that it
     * accepts @2.1::IMapper::BufferDescriptorInfo.
     *
     * 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.
     */
    createDescriptor_2_1(BufferDescriptorInfo descriptorInfo)
              generates (Error error,
                         BufferDescriptor descriptor);
};