graphics/allocator/2.0/IAllocator.hal

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

import android.hardware.graphics.common@1.0::PixelFormat;

interface IAllocator {
    enum Capability : int32_t {
        /* reserved */
        INVALID = 0,

        /*
         * testAllocate will always return UNDEFINED unless this capability
         * is supported.
         */
        TEST_ALLOCATE = 1,

        /*
         * layerCount must be 1 unless this capability is supported.
         */
        LAYERED_BUFFERS = 2,
    };

    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 producer usage mask; valid flags can be found in the
         * definition of ProducerUsage.
         */
        uint64_t producerUsageMask;

        /*
         * Buffer consumer usage mask; valid flags can be found in the
         * definition of ConsumerUsage.
         */
        uint64_t consumerUsageMask;
    };

    /*
     * Provides a list of supported capabilities (as described in the
     * definition of Capability above). This list must not change after
     * initialization.
     *
     * @return capabilities is a list of supported capabilities.
     */
    @entry
    @exit
    @callflow(next="*")
    getCapabilities() generates (vec<Capability> capabilities);

    /*
     * Retrieves implementation-defined debug information, which will be
     * displayed during, for example, `dumpsys SurfaceFlinger`.
     *
     * @return debugInfo is a string of debug information.
     */
    @entry
    @exit
    @callflow(next="*")
    dumpDebugInfo() generates (string debugInfo);

    /*
     * Creates a new, opaque buffer descriptor.
     *
     * @param descriptorInfo specifies the attributes of the buffer
     *        descriptor.
     * @return error is NONE upon success. Otherwise,
     *         BAD_VALUE when any attribute in descriptorInfo is invalid.
     *         NO_RESOURCES when no more descriptors can currently be created.
     * @return descriptor is the newly created buffer descriptor.
     */
    @entry
    @callflow(next="*")
    createDescriptor(BufferDescriptorInfo descriptorInfo)
          generates (Error error,
                     BufferDescriptor descriptor);

    /*
     * Destroys an existing buffer descriptor.
     *
     * @param descriptor is the descriptor to destroy.
     * @return error is either NONE or BAD_DESCRIPTOR.
     */
    @exit
    @callflow(next="*")
    destroyDescriptor(BufferDescriptor descriptor) generates (Error error);

    /*
     * Tests whether a buffer allocation can succeed, ignoring potential
     * resource contention which might lead to a NO_RESOURCES error.
     *
     * @param descriptors is a list of buffer descriptors.
     * @return error is NONE or NOT_SHARED upon success;
     *         NONE when buffers can be created and share a backing store.
     *         NOT_SHARED when buffers can be created but require more than a
     *                    backing store.
     *         Otherwise,
     *         BAD_DESCRIPTOR when any of the descriptors is invalid.
     *         UNSUPPORTED when any of the descriptors can never be satisfied.
     *         UNDEFINED when TEST_ALLOCATE is not listed in getCapabilities.
     */
    @callflow(next="allocate")
    testAllocate(vec<BufferDescriptor> descriptors) generates (Error error);

    /*
     * Attempts to allocate a list of buffers sharing a backing store.
     *
     * Each buffer will correspond to one of the descriptors passed into the
     * function and will hold a reference to its backing store. If the device
     * is unable to share the backing store between the buffers, it must
     * attempt to allocate the buffers with different backing stores and
     * return NOT_SHARED if it is successful.
     *
     * @param descriptors is the buffer descriptors to attempt to allocate.
     * @return error is NONE or NOT_SHARED upon success;
     *         NONE when buffers can be created and share a backing store.
     *         NOT_SHARED when buffers can be created but require more than a
     *                    backing store.
     *         Otherwise,
     *         BAD_DESCRIPTOR when any of the descriptors is invalid.
     *         UNSUPPORTED when any of the descriptors can never be satisfied.
     *         NO_RESOURCES when any of the buffers cannot be created at this
     *                      time.
     * @return buffers is the allocated buffers.
     */
    @callflow(next="exportHandle")
    allocate(vec<BufferDescriptor> descriptors)
        generates (Error error,
                   vec<Buffer> buffers);

    /*
     * Frees a buffer.
     *
     * @param buffer is the buffer to be freed.
     * @return error is NONE upon success. Otherwise,
     *         BAD_BUFFER when the buffer is invalid.
     */
    @exit
    @callflow(next="*")
    free(Buffer buffer) generates (Error error);

    /*
     * Exports a buffer for use in other client libraries or for cross-process
     * sharing.
     *
     * The exported handle is a handle to the backing store of the buffer, not
     * to the buffer itself. It however may not hold any reference to the
     * backing store and may be considered invalid by client libraries. To use
     * it and, in most cases, to save it for later use, a client must make a
     * clone of the handle and have the cloned handle hold a reference to the
     * backing store. Such a cloned handle will stay valid even after the
     * original buffer is freed. Refer to native_handle_clone and IMapper for
     * how a handle is cloned and how a reference is added.
     *
     * @param descriptor is the descriptor used to allocate the buffer.
     * @param buffer is the buffer to be exported.
     * @return error is NONE upon success. Otherwise,
     *         BAD_DESCRIPTOR when the descriptor is invalid.
     *         BAD_BUFFER when the buffer is invalid.
     *         BAD_VALUE when descriptor and buffer do not match.
     *         NO_RESOURCES when the buffer cannot be exported at this time.
     * @return bufferHandle is the exported handle.
     */
    @callflow(next="free")
    exportHandle(BufferDescriptor descriptor,
                 Buffer buffer)
      generates (Error error,
                 handle bufferHandle);
};