1Name 2 3 ANDROID_create_native_client_buffer 4 5Name Strings 6 7 EGL_ANDROID_create_native_client_buffer 8 9Contributors 10 11 Craig Donner 12 13Contact 14 15 Craig Donner, Google Inc. (cdonner 'at' google.com) 16 17Status 18 19 Draft 20 21Version 22 23 Version 1, January 19, 2016 24 25Number 26 27 EGL Extension #XXX 28 29Dependencies 30 31 Requires EGL 1.2. 32 33 EGL_ANDROID_image_native_buffer and EGL_KHR_image_base are required. 34 35 This extension is written against the wording of the EGL 1.2 36 Specification as modified by EGL_KHR_image_base and 37 EGL_ANDROID_image_native_buffer. 38 39Overview 40 41 This extension allows creating an EGLClientBuffer backed by an Android 42 window buffer (struct ANativeWindowBuffer) which can be later used to 43 create an EGLImage. 44 45New Types 46 47 None. 48 49New Procedures and Functions 50 51EGLClientBuffer eglCreateNativeClientBufferANDROID( 52 const EGLint *attrib_list) 53 54New Tokens 55 56 EGL_NATIVE_BUFFER_USAGE_ANDROID 0x3143 57 EGL_NATIVE_BUFFER_USAGE_PROTECTED_BIT_ANDROID 0x00000001 58 EGL_NATIVE_BUFFER_USAGE_RENDERBUFFER_BIT_ANDROID 0x00000002 59 EGL_NATIVE_BUFFER_USAGE_TEXTURE_BIT_ANDROID 0x00000004 60 61Changes to Chapter 3 of the EGL 1.2 Specification (EGL Functions and Errors) 62 63 Add the following to section 2.5.1 "EGLImage Specification" (as modified by 64 the EGL_KHR_image_base and EGL_ANDROID_image_native_buffer specifications), 65 below the description of eglCreateImageKHR: 66 67 "The command 68 69 EGLClientBuffer eglCreateNativeClientBufferANDROID( 70 const EGLint *attrib_list) 71 72 may be used to create an EGLClientBuffer backed by an ANativeWindowBuffer 73 struct. EGL implementations must guarantee that the lifetime of the 74 returned EGLClientBuffer is at least as long as the EGLImage(s) it is bound 75 to, following the lifetime semantics described below in section 2.5.2; the 76 EGLClientBuffer must be destroyed no earlier than when all of its associated 77 EGLImages are destroyed by eglDestroyImageKHR. <attrib_list> is a list of 78 attribute-value pairs which is used to specify the dimensions, format, and 79 usage of the underlying buffer structure. If <attrib_list> is non-NULL, the 80 last attribute specified in the list must be EGL_NONE. 81 82 Attribute names accepted in <attrib_list> are shown in Table aaa, 83 together with the <target> for which each attribute name is valid, and 84 the default value used for each attribute if it is not included in 85 <attrib_list>. 86 87 +---------------------------------+----------------------+---------------+ 88 | Attribute | Description | Default Value | 89 | | | | 90 +---------------------------------+----------------------+---------------+ 91 | EGL_NONE | Marks the end of the | N/A | 92 | | attribute-value list | | 93 | EGL_WIDTH | The width of the | 0 | 94 | | buffer data | | 95 | EGL_HEIGHT | The height of the | 0 | 96 | | buffer data | | 97 | EGL_RED_SIZE | The bits of Red in | 0 | 98 | | the color buffer | | 99 | EGL_GREEN_SIZE | The bits of Green in | 0 | 100 | | the color buffer | | 101 | EGL_BLUE_SIZE | The bits of Blue in | 0 | 102 | | the color buffer | | 103 | EGL_ALPHA_SIZE | The bits of Alpha in | 0 | 104 | | the color buffer | | 105 | | buffer data | | 106 | EGL_NATIVE_BUFFER_USAGE_ANDROID | The usage bits of | 0 | 107 | | the buffer data | | 108 +---------------------------------+----------------------+---------------+ 109 Table aaa. Legal attributes for eglCreateNativeClientBufferANDROID 110 <attrib_list> parameter. 111 112 The maximum width and height may depend on the amount of available memory, 113 which may also depend on the format and usage flags. The values of 114 EGL_RED_SIZE, EGL_GREEN_SIZE, and EGL_BLUE_SIZE must be non-zero and 115 correspond to a valid pixel format for the implementation. If EGL_ALPHA_SIZE 116 is non-zero then the combination of all four sizes must correspond to a 117 valid pixel format for the implementation. The 118 EGL_NATIVE_BUFFER_USAGE_ANDROID flag may include any of the following bits: 119 120 EGL_NATIVE_BUFFER_USAGE_PROTECTED_BIT_ANDROID: Indicates that the 121 created buffer must have a hardware-protected path to external display 122 sink. If a hardware-protected path is not available, then either don't 123 composite only this buffer (preferred) to the external sink, or (less 124 desirable) do not route the entire composition to the external sink. 125 126 EGL_NATIVE_BUFFER_USAGE_RENDERBUFFER_BIT_ANDROID: The buffer will be 127 used to create a color-renderable texture. 128 129 EGL_NATIVE_BUFFER_USAGE_TEXTURE_BIT_ANDROID: The buffer will be used to 130 create a filterable texture. 131 132 Errors 133 134 If eglCreateNativeClientBufferANDROID fails, NULL will be returned, no 135 memory will be allocated, and one of the following errors will be 136 generated: 137 138 * If the value of EGL_WIDTH or EGL_HEIGHT is not positive, the error 139 EGL_BAD_PARAMETER is generated. 140 141 * If the combination of the values of EGL_RED_SIZE, EGL_GREEN_SIZE, 142 EGL_BLUE_SIZE, and EGL_ALPHA_SIZE is not a valid pixel format for the 143 EGL implementation, the error EGL_BAD_PARAMETER is generated. 144 145 * If the value of EGL_NATIVE_BUFFER_ANDROID is not a valid combination 146 of gralloc usage flags for the EGL implementation, or is incompatible 147 with the value of EGL_FORMAT, the error EGL_BAD_PARAMETER is 148 Generated. 149 150Issues 151 152 1. Should this extension define what combinations of formats and usage flags 153 EGL implementations are required to support? 154 155 RESOLVED: Partially. 156 157 The set of valid color combinations is implementation-specific and may 158 depend on additional EGL extensions, but generally RGB565 and RGBA888 should 159 be supported. The particular valid combinations for a given Android version 160 and implementation should be documented by that version. 161 162 2. Should there be an eglDestroyNativeClientBufferANDROID to destroy the 163 client buffers created by this extension? 164 165 RESOLVED: No. 166 167 A destroy function would add several complications: 168 169 a) ANativeWindowBuffer is a reference counted object, may be used 170 outside of EGL. 171 b) The same buffer may back multiple EGLImages, though this usage may 172 result in undefined behavior. 173 c) The interactions between the lifetimes of EGLImages and their 174 EGLClientBuffers would become needlessly complex. 175 176 Because ANativeWindowBuffer is a reference counted object, implementations 177 of this extension should ensure the buffer has a lifetime at least as long 178 as a generated EGLImage (via EGL_ANDROID_image_native_buffer). The simplest 179 method is to increment the reference count of the buffer in 180 eglCreateImagKHR, and then decrement it in eglDestroyImageKHR. This should 181 ensure proper lifetime semantics. 182 183Revision History 184 185#2 (Craig Donner, April 15, 2016) 186 - Set color formats and usage bits explicitly using additional attributes, 187 and add value for new token EGL_NATIVE_BUFFER_USAGE_ANDROID. 188 189#1 (Craig Donner, January 19, 2016) 190 - Initial draft. 191