graphics/mapper/2.0/IMapper.hal - LeafOS-Project/android_hardware_interfaces - Gitiles

 /*
  * 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);
 };
	/*
	* 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);
	};