From: Craig Donner Date: Fri, 15 Apr 2016 16:41:25 +0000 (-0700) Subject: Adds spec for EGL_ANDROID_create_native_client_buffer. X-Git-Tag: android-x86-7.1-r1~318^2 X-Git-Url: http://git.osdn.net/view?a=commitdiff_plain;h=fcd6a9c30058078d4bef7ff08f81ff2b955a9a2f;p=android-x86%2Fframeworks-native.git Adds spec for EGL_ANDROID_create_native_client_buffer. Change-Id: I7dacf234a3b5f5f9c50a0b4c0f5b82618f6bd09d Fixes: 28210230 --- diff --git a/opengl/specs/EGL_ANDROID_create_native_client_buffer.txt b/opengl/specs/EGL_ANDROID_create_native_client_buffer.txt new file mode 100644 index 0000000000..a6fae80d7d --- /dev/null +++ b/opengl/specs/EGL_ANDROID_create_native_client_buffer.txt @@ -0,0 +1,197 @@ +Name + + ANDROID_create_native_client_buffer + +Name Strings + + EGL_ANDROID_create_native_client_buffer + +Contributors + + Craig Donner + +Contact + + Craig Donner, Google Inc. (cdonner 'at' google.com) + +Status + + Draft + +Version + + Version 1, January 19, 2016 + +Number + + EGL Extension #XXX + +Dependencies + + Requires EGL 1.2. + + EGL_ANDROID_image_native_buffer and EGL_KHR_image_base are required. + + This extension is written against the wording of the EGL 1.2 + Specification as modified by EGL_KHR_image_base and + EGL_ANDROID_image_native_buffer. + +Overview + + This extension allows creating an EGLClientBuffer backed by an Android + window buffer (struct ANativeWindowBuffer) which can be later used to + create an EGLImage. + +New Types + + None. + +New Procedures and Functions + +EGLClientBuffer eglCreateNativeClientBufferANDROID( + const EGLint *attrib_list) + +New Tokens + + EGL_NATIVE_BUFFER_USAGE_ANDROID 0x3143 + EGL_NATIVE_BUFFER_USAGE_PROTECTED_BIT_ANDROID 0x00000001 + EGL_NATIVE_BUFFER_USAGE_RENDERBUFFER_BIT_ANDROID 0x00000002 + EGL_NATIVE_BUFFER_USAGE_TEXTURE_BIT_ANDROID 0x00000004 + +Changes to Chapter 3 of the EGL 1.2 Specification (EGL Functions and Errors) + + Add the following to section 2.5.1 "EGLImage Specification" (as modified by + the EGL_KHR_image_base and EGL_ANDROID_image_native_buffer specifications), + below the description of eglCreateImageKHR: + + "The command + + EGLClientBuffer eglCreateNativeClientBufferANDROID( + const EGLint *attrib_list) + + may be used to create an EGLClientBuffer backed by an ANativeWindowBuffer + struct. EGL implementations must guarantee that the lifetime of the + returned EGLClientBuffer is at least as long as the EGLImage(s) it is bound + to, following the lifetime semantics described below in section 2.5.2; the + EGLClientBuffer must be destroyed no earlier than when all of its associated + EGLImages are destroyed by eglDestroyImageKHR. is a list of + attribute-value pairs which is used to specify the dimensions, format, and + usage of the underlying buffer structure. If is non-NULL, the + last attribute specified in the list must be EGL_NONE. + + Attribute names accepted in are shown in Table aaa, + together with the for which each attribute name is valid, and + the default value used for each attribute if it is not included in + . + + +---------------------------------+----------------------+---------------+ + | Attribute | Description | Default Value | + | | | | + +---------------------------------+----------------------+---------------+ + | EGL_NONE | Marks the end of the | N/A | + | | attribute-value list | | + | EGL_WIDTH | The width of the | 0 | + | | buffer data | | + | EGL_HEIGHT | The height of the | 0 | + | | buffer data | | + | EGL_RED_SIZE | The bits of Red in | 0 | + | | the color buffer | | + | EGL_GREEN_SIZE | The bits of Green in | 0 | + | | the color buffer | | + | EGL_BLUE_SIZE | The bits of Blue in | 0 | + | | the color buffer | | + | EGL_ALPHA_SIZE | The bits of Alpha in | 0 | + | | the color buffer | | + | | buffer data | | + | EGL_NATIVE_BUFFER_USAGE_ANDROID | The usage bits of | 0 | + | | the buffer data | | + +---------------------------------+----------------------+---------------+ + Table aaa. Legal attributes for eglCreateNativeClientBufferANDROID + parameter. + + The maximum width and height may depend on the amount of available memory, + which may also depend on the format and usage flags. The values of + EGL_RED_SIZE, EGL_GREEN_SIZE, and EGL_BLUE_SIZE must be non-zero and + correspond to a valid pixel format for the implementation. If EGL_ALPHA_SIZE + is non-zero then the combination of all four sizes must correspond to a + valid pixel format for the implementation. The + EGL_NATIVE_BUFFER_USAGE_ANDROID flag may include any of the following bits: + + EGL_NATIVE_BUFFER_USAGE_PROTECTED_BIT_ANDROID: Indicates that the + created buffer must have a hardware-protected path to external display + sink. If a hardware-protected path is not available, then either don't + composite only this buffer (preferred) to the external sink, or (less + desirable) do not route the entire composition to the external sink. + + EGL_NATIVE_BUFFER_USAGE_RENDERBUFFER_BIT_ANDROID: The buffer will be + used to create a renderbuffer. This flag must not be set if + EGL_NATIVE_BUFFER_USAGE_TEXTURE_BIT_ANDROID is set. + + EGL_NATIVE_BUFFER_USAGE_TEXTURE_BIT_ANDROID: The buffer will be used to + create a texture. This flag must not be set if + EGL_NATIVE_BUFFER_USAGE_RENDERBUFFER_BIT_ANDROID is set. + + Errors + + If eglCreateNativeClientBufferANDROID fails, NULL will be returned, no + memory will be allocated, and one of the following errors will be + generated: + + * If the value of EGL_WIDTH or EGL_HEIGHT is not positive, the error + EGL_BAD_PARAMETER is generated. + + * If the combination of the values of EGL_RED_SIZE, EGL_GREEN_SIZE, + EGL_BLUE_SIZE, and EGL_ALPHA_SIZE is not a valid pixel format for the + EGL implementation, the error EGL_BAD_PARAMETER is generated. + + * If the value of EGL_NATIVE_BUFFER_ANDROID is not a valid combination + of gralloc usage flags for the EGL implementation, or is incompatible + with the value of EGL_FORMAT, the error EGL_BAD_PARAMETER is + Generated. + + * If both the EGL_NATIVE_BUFFER_USAGE_RENDERBUFFER_BIT_ANDROID and + EGL_NATIVE_BUFFER_USAGE_TEXTURE_BIT_ANDROID are set in the value of + EGL_NATIVE_BUFFER_USAGE_ANDROID, the error EGL_BAD_PARAMETER is + Generated." + +Issues + + 1. Should this extension define what combinations of formats and usage flags + EGL implementations are required to support? + + RESOLVED: Partially. + + The set of valid color combinations is implementation-specific and may + depend on additional EGL extensions, but generally RGB565 and RGBA888 should + be supported. The particular valid combinations for a given Android version + and implementation should be documented by that version. + + 2. Should there be an eglDestroyNativeClientBufferANDROID to destroy the + client buffers created by this extension? + + RESOLVED: No. + + A destroy function would add several complications: + + a) ANativeWindowBuffer is a reference counted object, may be used + outside of EGL. + b) The same buffer may back multiple EGLImages, though this usage may + result in undefined behavior. + c) The interactions between the lifetimes of EGLImages and their + EGLClientBuffers would become needlessly complex. + + Because ANativeWindowBuffer is a reference counted object, implementations + of this extension should ensure the buffer has a lifetime at least as long + as a generated EGLImage (via EGL_ANDROID_image_native_buffer). The simplest + method is to increment the reference count of the buffer in + eglCreateImagKHR, and then decrement it in eglDestroyImageKHR. This should + ensure proper lifetime semantics. + +Revision History + +#2 (Craig Donner, April 15, 2016) + - Set color formats and usage bits explicitly using additional attributes, + and add value for new token EGL_NATIVE_BUFFER_USAGE_ANDROID. + +#1 (Craig Donner, January 19, 2016) + - Initial draft.