frameworks/native: Fixes for AHardwareBuffer, ANativeWindow and ARect docs. (bd5cb48d) · Commits · e / os / android_frameworks_native-old

libs/arect/include/android/rect.h

+11 −8

Original line number	Diff line number	Diff line
		@@ -33,23 +33,26 @@ extern "C" {
		#endif

		/**
		* {@link ARect} is a struct that represents a rectangular window area.
		* Rectangular window area.
		*
		* It is used with {@link
		* ANativeActivityCallbacks::onContentRectChanged} event callback and
		* ANativeWindow_lock() function.
		* This is the NDK equivalent of the android.graphics.Rect class in Java. It is
		* used with {@link ANativeActivityCallbacks::onContentRectChanged} event
		* callback and the ANativeWindow_lock() function.
		*
		* In a valid ARect, left <= right and top <= bottom. ARect with left=0, top=10,
		* right=1, bottom=11 contains only one pixel at x=0, y=10.
		*/
		typedef struct ARect {
		#ifdef __cplusplus
		typedef int32_t value_type;
		#endif
		/** left position */
		/// Minimum X coordinate of the rectangle.
		int32_t left;
		/** top position */
		/// Minimum Y coordinate of the rectangle.
		int32_t top;
		/** left position */
		/// Maximum X coordinate of the rectangle.
		int32_t right;
		/** bottom position */
		/// Maximum Y coordinate of the rectangle.
		int32_t bottom;
		} ARect;

libs/nativewindow/include/android/hardware_buffer.h

+57 −42

Original line number	Diff line number	Diff line
		@@ -41,9 +41,11 @@ enum {
		AHARDWAREBUFFER_FORMAT_R8G8B8A8_UNORM = 1,

		/**
		* 32 bits per pixel, 8 bits per channel format where alpha values are
		* ignored (always opaque).
		* Corresponding formats:
		* Vulkan: VK_FORMAT_R8G8B8A8_UNORM
		* OpenGL ES: GL_RGBA8
		* OpenGL ES: GL_RGB8
		*/
		AHARDWAREBUFFER_FORMAT_R8G8B8X8_UNORM = 2,

		@@ -124,40 +126,49 @@ enum {
		AHARDWAREBUFFER_FORMAT_S8_UINT = 0x35,
		};

		/**
		* Buffer usage flags, specifying how the buffer will be accessed.
		*/
		enum {
		/* The buffer will never be read by the CPU */
		/// The buffer will never be read by the CPU.
		AHARDWAREBUFFER_USAGE_CPU_READ_NEVER = 0UL,
		/* The buffer will sometimes be read by the CPU */
		/// The buffer will sometimes be read by the CPU.
		AHARDWAREBUFFER_USAGE_CPU_READ_RARELY = 2UL,
		/* The buffer will often be read by the CPU */
		/// The buffer will often be read by the CPU.
		AHARDWAREBUFFER_USAGE_CPU_READ_OFTEN = 3UL,
		/* CPU read value mask */
		/// CPU read value mask.
		AHARDWAREBUFFER_USAGE_CPU_READ_MASK = 0xFUL,

		/* The buffer will never be written by the CPU */
		/// The buffer will never be written by the CPU.
		AHARDWAREBUFFER_USAGE_CPU_WRITE_NEVER = 0UL << 4,
		/* The buffer will sometimes be written to by the CPU */
		/// The buffer will sometimes be written to by the CPU.
		AHARDWAREBUFFER_USAGE_CPU_WRITE_RARELY = 2UL << 4,
		/* The buffer will often be written to by the CPU */
		/// The buffer will often be written to by the CPU.
		AHARDWAREBUFFER_USAGE_CPU_WRITE_OFTEN = 3UL << 4,
		/* CPU write value mask */
		/// CPU write value mask.
		AHARDWAREBUFFER_USAGE_CPU_WRITE_MASK = 0xFUL << 4,

		/* The buffer will be read from by the GPU */
		/// The buffer will be read from by the GPU as a texture.
		AHARDWAREBUFFER_USAGE_GPU_SAMPLED_IMAGE = 1UL << 8,
		/* The buffer will be written to by the GPU */
		/**
		* The buffer will be written to by the GPU as a framebuffer attachment.
		* Note that the name of this flag is somewhat misleading: it does not imply
		* that the buffer contains a color format. A buffer with depth or stencil
		* format that will be used as a framebuffer attachment should also have
		* this flag.
		*/
		AHARDWAREBUFFER_USAGE_GPU_COLOR_OUTPUT = 1UL << 9,
		/* The buffer must not be used outside of a protected hardware path */
		/// The buffer must not be used outside of a protected hardware path.
		AHARDWAREBUFFER_USAGE_PROTECTED_CONTENT = 1UL << 14,
		/* The buffer will be read by a hardware video encoder */
		/// The buffer will be read by a hardware video encoder.
		AHARDWAREBUFFER_USAGE_VIDEO_ENCODE = 1UL << 16,
		/* The buffer will be used for sensor direct data */
		/// The buffer will be used for direct writes from sensors.
		AHARDWAREBUFFER_USAGE_SENSOR_DIRECT_DATA = 1UL << 23,
		/* The buffer will be used as a shader storage or uniform buffer object */
		/// The buffer will be used as a shader storage or uniform buffer object.
		AHARDWAREBUFFER_USAGE_GPU_DATA_BUFFER = 1UL << 24,
		/* The buffer will be used as a cube map texture */
		/// The buffer will be used as a cube map texture.
		AHARDWAREBUFFER_USAGE_GPU_CUBE_MAP = 1UL << 25,
		/* The buffer contains a complete mipmap hierarchy */
		/// The buffer contains a complete mipmap hierarchy.
		AHARDWAREBUFFER_USAGE_GPU_MIPMAP_COMPLETE = 1UL << 26,

		AHARDWAREBUFFER_USAGE_VENDOR_0 = 1ULL << 28,
		@@ -182,15 +193,19 @@ enum {
		AHARDWAREBUFFER_USAGE_VENDOR_19 = 1ULL << 63,
		};

		/**
		* Buffer description. Used for allocating new buffers and querying parameters
		* of existing ones.
		*/
		typedef struct AHardwareBuffer_Desc {
		uint32_t width; // width in pixels
		uint32_t height; // height in pixels
		uint32_t layers; // number of images
		uint32_t format; // One of AHARDWAREBUFFER_FORMAT_*
		uint64_t usage; // Combination of AHARDWAREBUFFER_USAGE_*
		uint32_t stride; // Stride in pixels, ignored for AHardwareBuffer_allocate()
		uint32_t rfu0; // Initialize to zero, reserved for future use
		uint64_t rfu1; // Initialize to zero, reserved for future use
		uint32_t width; ///< Width in pixels.
		uint32_t height; ///< Height in pixels.
		uint32_t layers; ///< Number of images in an image array.
		uint32_t format; ///< One of AHARDWAREBUFFER_FORMAT_*
		uint64_t usage; ///< Combination of AHARDWAREBUFFER_USAGE_*
		uint32_t stride; ///< Row stride in pixels, ignored for AHardwareBuffer_allocate()
		uint32_t rfu0; ///< Initialize to zero, reserved for future use.
		uint64_t rfu1; ///< Initialize to zero, reserved for future use.
		} AHardwareBuffer_Desc;

		typedef struct AHardwareBuffer AHardwareBuffer;
		@@ -199,8 +214,8 @@ typedef struct AHardwareBuffer AHardwareBuffer;
		* Allocates a buffer that backs an AHardwareBuffer using the passed
		* AHardwareBuffer_Desc.
		*
		* Returns NO_ERROR on success, or an error number of the allocation fails for
		* any reason.
		* \return NO_ERROR on success, or an error number of the allocation fails for
		* any reason. The returned buffer has a reference count of 1.
		*/
		int AHardwareBuffer_allocate(const AHardwareBuffer_Desc* desc,
		AHardwareBuffer** outBuffer);
		@@ -223,7 +238,7 @@ void AHardwareBuffer_release(AHardwareBuffer* buffer);
		void AHardwareBuffer_describe(const AHardwareBuffer* buffer,
		AHardwareBuffer_Desc* outDesc);

		/*
		/**
		* Lock the AHardwareBuffer for reading or writing, depending on the usage flags
		* passed. This call may block if the hardware needs to finish rendering or if
		* CPU caches need to be synchronized, or possibly for other implementation-
		@@ -231,16 +246,16 @@ void AHardwareBuffer_describe(const AHardwareBuffer* buffer,
		* descriptor that will be signaled when the buffer is locked, otherwise the
		* caller will block until the buffer is available.
		*
		* If rect is not NULL, the caller promises to modify only data in the area
		* If \a rect is not NULL, the caller promises to modify only data in the area
		* specified by rect. If rect is NULL, the caller may modify the contents of the
		* entire buffer.
		*
		* The content of the buffer outside of the specified rect is NOT modified
		* by this call.
		*
		* The buffer usage may only specify AHARDWAREBUFFER_USAGE_CPU_*. If set, then
		* outVirtualAddress is filled with the address of the buffer in virtual memory,
		* otherwise this function will fail.
		* The \a usage parameter may only specify AHARDWAREBUFFER_USAGE_CPU_*. If set,
		* then outVirtualAddress is filled with the address of the buffer in virtual
		* memory.
		*
		* THREADING CONSIDERATIONS:
		*
		@@ -252,38 +267,38 @@ void AHardwareBuffer_describe(const AHardwareBuffer* buffer,
		* may return an error or leave the buffer's content into an indeterminate
		* state.
		*
		* Returns NO_ERROR on success, BAD_VALUE if the buffer is NULL or if the usage
		* \return NO_ERROR on success, BAD_VALUE if \a buffer is NULL or if the usage
		* flags are not a combination of AHARDWAREBUFFER_USAGE_CPU_*, or an error
		* number of the lock fails for any reason.
		*/
		int AHardwareBuffer_lock(AHardwareBuffer* buffer, uint64_t usage,
		int32_t fence, const ARect* rect, void** outVirtualAddress);

		/*
		/**
		* Unlock the AHardwareBuffer; must be called after all changes to the buffer
		* are completed by the caller. If fence is not NULL then it will be set to a
		* file descriptor that is signaled when all pending work on the buffer is
		* completed. The caller is responsible for closing the fence when it is no
		* longer needed.
		*
		* Returns NO_ERROR on success, BAD_VALUE if the buffer is NULL, or an error
		* number of the lock fails for any reason.
		* \return NO_ERROR on success, BAD_VALUE if \a buffer is NULL, or an error
		* number if the unlock fails for any reason.
		*/
		int AHardwareBuffer_unlock(AHardwareBuffer* buffer, int32_t* fence);

		/*
		/**
		* Send the AHardwareBuffer to an AF_UNIX socket.
		*
		* Returns NO_ERROR on success, BAD_VALUE if the buffer is NULL, or an error
		* number of the lock fails for any reason.
		* \return NO_ERROR on success, BAD_VALUE if \a buffer is NULL, or an error
		* number if the operation fails for any reason.
		*/
		int AHardwareBuffer_sendHandleToUnixSocket(const AHardwareBuffer* buffer, int socketFd);

		/*
		/**
		* Receive the AHardwareBuffer from an AF_UNIX socket.
		*
		* Returns NO_ERROR on success, BAD_VALUE if the buffer is NULL, or an error
		* number of the lock fails for any reason.
		* \return NO_ERROR on success, BAD_VALUE if \a outBuffer is NULL, or an error
		* number if the operation fails for any reason.
		*/
		int AHardwareBuffer_recvHandleFromUnixSocket(int socketFd, AHardwareBuffer** outBuffer);

libs/nativewindow/include/android/native_window.h

+7 −7

Original line number	Diff line number	Diff line
		@@ -85,23 +85,23 @@ typedef struct ANativeWindow ANativeWindow;
		* A pointer can be obtained using {@link ANativeWindow_lock()}.
		*/
		typedef struct ANativeWindow_Buffer {
		// The number of pixels that are show horizontally.
		/// The number of pixels that are shown horizontally.
		int32_t width;

		// The number of pixels that are shown vertically.
		/// The number of pixels that are shown vertically.
		int32_t height;

		// The number of pixels that a line in the buffer takes in
		// memory. This may be >= width.
		/// The number of pixels that a line in the buffer takes in
		/// memory. This may be >= width.
		int32_t stride;

		// The format of the buffer. One of AHARDWAREBUFFER_FORMAT_*
		/// The format of the buffer. One of AHARDWAREBUFFER_FORMAT_*
		int32_t format;

		// The actual bits.
		/// The actual bits.
		void* bits;

		// Do not touch.
		/// Do not touch.
		uint32_t reserved[6];
		} ANativeWindow_Buffer;