1 Name 2 3 ANDROID_create_native_client_buffer 4 5 Name Strings 6 7 EGL_ANDROID_create_native_client_buffer 8 9 Contributors 10 11 Craig Donner 12 13 Contact 14 15 Craig Donner, Google Inc. (cdonner 'at' google.com) 16 17 Status 18 19 Draft 20 21 Version 22 23 Version 1, January 19, 2016 24 25 Number 26 27 EGL Extension #XXX 28 29 Dependencies 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 39 Overview 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 45 New Types 46 47 None. 48 49 New Procedures and Functions 50 51 EGLClientBuffer eglCreateNativeClientBufferANDROID( 52 const EGLint *attrib_list) 53 54 New 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 61 Changes 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 renderbuffer. This flag must not be set if 128 EGL_NATIVE_BUFFER_USAGE_TEXTURE_BIT_ANDROID is set. 129 130 EGL_NATIVE_BUFFER_USAGE_TEXTURE_BIT_ANDROID: The buffer will be used to 131 create a texture. This flag must not be set if 132 EGL_NATIVE_BUFFER_USAGE_RENDERBUFFER_BIT_ANDROID is set. 133 134 Errors 135 136 If eglCreateNativeClientBufferANDROID fails, NULL will be returned, no 137 memory will be allocated, and one of the following errors will be 138 generated: 139 140 * If the value of EGL_WIDTH or EGL_HEIGHT is not positive, the error 141 EGL_BAD_PARAMETER is generated. 142 143 * If the combination of the values of EGL_RED_SIZE, EGL_GREEN_SIZE, 144 EGL_BLUE_SIZE, and EGL_ALPHA_SIZE is not a valid pixel format for the 145 EGL implementation, the error EGL_BAD_PARAMETER is generated. 146 147 * If the value of EGL_NATIVE_BUFFER_ANDROID is not a valid combination 148 of gralloc usage flags for the EGL implementation, or is incompatible 149 with the value of EGL_FORMAT, the error EGL_BAD_PARAMETER is 150 Generated. 151 152 * If both the EGL_NATIVE_BUFFER_USAGE_RENDERBUFFER_BIT_ANDROID and 153 EGL_NATIVE_BUFFER_USAGE_TEXTURE_BIT_ANDROID are set in the value of 154 EGL_NATIVE_BUFFER_USAGE_ANDROID, the error EGL_BAD_PARAMETER is 155 Generated." 156 157 Issues 158 159 1. Should this extension define what combinations of formats and usage flags 160 EGL implementations are required to support? 161 162 RESOLVED: Partially. 163 164 The set of valid color combinations is implementation-specific and may 165 depend on additional EGL extensions, but generally RGB565 and RGBA888 should 166 be supported. The particular valid combinations for a given Android version 167 and implementation should be documented by that version. 168 169 2. Should there be an eglDestroyNativeClientBufferANDROID to destroy the 170 client buffers created by this extension? 171 172 RESOLVED: No. 173 174 A destroy function would add several complications: 175 176 a) ANativeWindowBuffer is a reference counted object, may be used 177 outside of EGL. 178 b) The same buffer may back multiple EGLImages, though this usage may 179 result in undefined behavior. 180 c) The interactions between the lifetimes of EGLImages and their 181 EGLClientBuffers would become needlessly complex. 182 183 Because ANativeWindowBuffer is a reference counted object, implementations 184 of this extension should ensure the buffer has a lifetime at least as long 185 as a generated EGLImage (via EGL_ANDROID_image_native_buffer). The simplest 186 method is to increment the reference count of the buffer in 187 eglCreateImagKHR, and then decrement it in eglDestroyImageKHR. This should 188 ensure proper lifetime semantics. 189 190 Revision History 191 192 #2 (Craig Donner, April 15, 2016) 193 - Set color formats and usage bits explicitly using additional attributes, 194 and add value for new token EGL_NATIVE_BUFFER_USAGE_ANDROID. 195 196 #1 (Craig Donner, January 19, 2016) 197 - Initial draft. 198
