1Name 2 3 EXT_compositor 4 5Name Strings 6 7 EGL_EXT_compositor 8 9Contributors 10 11 Marc Moody 12 Daniel Herring 13 14Contacts 15 16 Marc Moody, Boeing Inc., marc dot d dot moody at boeing dot com 17 Daniel Herring, Core Avionics & Industrial Inc., daniel dot herring at ch1group dot com 18 19Status 20 21 Complete 22 23Version 24 Version 1.0, February 3, 2017 25 26Number 27 28 EGL Extension #116 29 30Dependencies 31 32 Requires EGL 1.0. 33 34 This extension is written against the wording of the EGL 1.4 35 Specification - April 6, 2011, but may be implemented against earlier 36 versions. 37 38Overview 39 40 This extension allows for the composition of multiple windows within 41 a multi-partition EGL system. The extension allows a primary EGLContext and 42 window to be created for each display. All other windows are created using 43 non-displayable surfaces. A handle to each off-screen window is provided 44 to the primary EGLContext to allow the composition of all non-displayable windows 45 on a single display. 46 47 For each display, there is one EGLContext which has access to create on screen 48 windows, this is call the primary context for this display. All other EGLContexts 49 are referred to as secondary contexts. 50 51 This extension requires a multi-partition EGL driver to support asynchronous 52 rendering of off screen surfaces. 53 54 Information assurance is provided by preventing context and surface creation by 55 unregistered contexts and by preventing the non-primary contexts and surfaces 56 from rendering to the display. 57 58New Types 59 60 None 61 62New Procedures and Functions 63 64 EGLBoolean eglCompositorSetContextListEXT (const EGLint *external_ref_ids, 65 EGLint num_entries); 66 67 EGLBoolean eglCompositorSetContextAttributesEXT (EGLint external_ref_id, 68 const EGLint *context_attributes, 69 EGLint num_entries); 70 71 EGLBoolean eglCompositorSetWindowListEXT (EGLint external_ref_id, 72 const EGLint *external_win_ids, 73 EGLint num_entries); 74 75 EGLBoolean eglCompositorSetWindowAttributesEXT (EGLint external_win_id, 76 const EGLint *window_attributes, 77 EGLint num_entries); 78 79 EGLBoolean eglCompositorBindTexWindowEXT (EGLint external_win_id); 80 81 EGLBoolean eglCompositorSetSizeEXT (EGLint external_win_id, 82 EGLint width, EGLint height); 83 84 EGLBoolean eglCompositorSwapPolicyEXT (EGLint external_win_id, 85 EGLint policy); 86 87 88New Tokens 89 90 New attributes accepted by the <attrib_list> argument of 91 eglCreateContext: 92 93 EGL_PRIMARY_COMPOSITOR_CONTEXT_EXT 0x3460 94 95 New attributes accepted by the <attrib_list> argument of 96 eglCreateContext and eglCreateWindowSurface: 97 98 EGL_EXTERNAL_REF_ID_EXT 0x3461 99 100 New attributes accepted by the <policy> argument of 101 eglCompositorSwapPolicyHint: 102 103 EGL_COMPOSITOR_DROP_NEWEST_FRAME_EXT 0x3462 104 105 EGL_COMPOSITOR_KEEP_NEWEST_FRAME_EXT 0x3463 106 107Modify Section 3.7.1 of the EGL 1.4 Specification, paragraph 2 108 (Creating Rendering Contexts) on pg. 43 109 From: 110 If eglCreateContext succeeds, it initializes the context to the initial state defined 111 for the current rendering API, and returns a handle to it. The context can be 112 used to render to any compatible EGLSurface. 113 114 To: 115 If eglCreateContext succeeds, it initializes the context to the initial state defined 116 for the current rendering API, and returns a handle to it. The context can be 117 used to render to any compatible off-screen rendering surface (Sections 3.5.2 118 and 3.5.4). A secondary context can be used to render to compatible window surfaces 119 which have been associated with the context using eglCompositorSetWindowListEXT. A 120 non-secondary context can be used to render to any compatible EGLSurface. 121 122Modify Section 3.7.1 of EGL 1.4 Specification, paragraph 5 123 (Creating Rendering Contexts) on pg. 43 124 From: 125 attrib_list specifies a list of attributes for the context. The list has the same 126 structure as described for eglChooseConfig. The only attribute that can be specified 127 in attrib_list is EGL_CONTEXT_CLIENT_VERSION, and this attribute may only 128 be specified when creating a OpenGL ES context (e.g. when the current rendering 129 API is EGL_OPENGL_ES_API). 130 131 To: 132 attrib_list specifies a list of attributes for the context. The list has the same 133 structure as described for eglChooseConfig. The attributes that can be specified 134 in attrib_list are EGL_CONTEXT_CLIENT_VERSION, EGL_PRIMARY_COMPOSITOR_CONTEXT_EXT, 135 EGL_EXTERNAL_REF_ID_EXT. 136 137Modify Section 3.7.1 of EGL 1.4 Specification, paragraph 7 138 (Creating Rendering Contexts) on pg. 43 139 From: 140 EGL_CONTEXT_CLIENT_VERSION determines which version of an OpenGL 141 ES context to create. An attribute value of 1 specifies creation of an OpenGL ES 142 1.x context. An attribute value of 2 specifies creation of an OpenGL ES 2.x context. 143 The default value for EGL_CONTEXT_CLIENT_VERSION is 1. 144 145 To: 146 EGL_CONTEXT_CLIENT_VERSION determines which version of an OpenGL 147 ES context to create. An attribute value of 1 specifies creation of an OpenGL ES 148 1.x context. An attribute value of 2 specifies creation of an OpenGL ES 2.x context. 149 The default value for EGL_CONTEXT_CLIENT_VERSION is 1. EGL_CONTEXT_CLIENT_VERSION 150 may only be specified when creating a OpenGL ES context (e.g. when the current 151 rendering API is EGL_OPENGL_ES_API). 152 153Additions to Section 3.7.1 of the EGL 1.4 Specification (Creating Rendering Contexts). 154 155 The first call to eglCreateContext with EGL_PRIMARY_COMPOSITOR_CONTEXT_EXT 156 set as EGL_TRUE in the <attrib-list> returns an EGLContext handle which will 157 act as the primary context for the specified EGLDisplay. This shall be the 158 only context on this EGLDisplay which is able to be bound to an on-screen window 159 on the EGLDisplay. Subsequent calls to eglCreateContext, for the same display, 160 in any address space with EGL_PRIMIARY_COMPOSITOR_CONTEXT_EXT set as EGL_TRUE 161 shall return EGL_NO_CONTEXT. 162 Subsequent calls, in any address space for the same display, to eglCreateContext 163 which do not use EGL_PRIMARY_COMPOSITOR_CONTEXT_EXT should use the the attribute 164 EGL_EXTERNAL_REF_ID_EXT and an external reference identifier to create a valid 165 EGLContext. 166 Subsequent calls, in any address space for the same display, to eglCreateContext 167 which do not use EGL_PRIMARY_COMPOSITOR_CONTEXT_EXT and do not use 168 EGL_EXTERNAL_REF_ID_EXT shall not create a context and shall return 169 EGL_NO_CONTEXT and set the error EGL_BAD_ACCESS. 170 171 EGL_PRIMARY_COMPOSITOR_CONTEXT_EXT notifies EGL that this context is the only 172 context allowed to render to a on screen window surface for this display. This 173 attribute is followed in the attribute list by either EGL_TRUE or EGL_FALSE. 174 EGL_EXTERNAL_REF_ID_EXT is followed by an external reference identifier which 175 associates this context with the list of allowed contexts set by 176 eglCompositorSetContextListEXT. If the reference identifier has already been 177 used to initiate another call to eglCreateContext in any address space, this 178 call shall fail and set the error EGL_BAD_ATTRIBUTE. IF the external reference 179 identifier is not a valid identifier the error EGL_BAD_ATTRIBUTE shall be set 180 and the call shall fail. If this attribute is set and the primary context has 181 not yet been created then the error EGL_BAD_MATCH and the call shall fail. 182 183 Only when the attributes specified via attrib_list and those specified for this 184 context using eglCompositorSetContextAttributesEXT are compatible will the 185 context be successfully created. 186 187Modify the list of parameters supported by eglCreateWindowSurface in section 3.5.1 188 (Creating On-Screen Rendering Surfaces) on p. 27: 189 190 An external window identifier (EGLuint external_win_id) is associated with 191 each off screen window. EGLNativeWindowType shall be EGLint and the 192 external window identifier shall be used as the value for the <win> parameter. 193 EGL_EXTERNAL_REF_ID_EXT with the context external reference id shall be in the 194 attrib_list. If the external window identifier and the external reference identifier 195 do not match a pair set using eglCompositorSetWindowListEXT window creation shall 196 fail. 197 198Add the function: 199 200 EGLBoolean eglCompositorSetContextListEXT(const EGLint *external_ref_ids, 201 EGLint num_entries); 202 203 This function is called by the primary context to establish the set of 204 all allowable secondary contexts by defining the set of external reference 205 identifiers. Secondary contexts shall identify their external reference 206 identifier by setting the EGL_EXTERNAL_REF_ID_EXT attribute when calling 207 eglCreateContext. 208 Calls to this function when the primary context for the display is not active, 209 shall return EGL_FALSE and do nothing. When this function is successful it 210 shall return EGL_TRUE and associate the list of external reference identifiers 211 with the active display. 212 This function shall only be called once per primary context. Subsequent calls 213 shall return EGL_FALSE and do nothing. 214 215 external_ref_ids shall be an array of user generated integers greater than 1. 216 num_entries shall specify the number of external_ref_ids. 217 218Add the function: 219 220 EGLBoolean eglCompositorSetContextAttributesEXT (EGLint external_ref_id, 221 const EGLint *context_attributes, 222 EGLint num_entries); 223 224 This function is called by the primary context to establish a list of compatible 225 context attributes. 226 Calls to this function when the primary context for the display is not active 227 shall return EGL_FALSE and do nothing. When the function is successful it shall 228 return EGL_TRUE and associate the given attributes to the subsequent 229 eglCreateContext call using the given external reference id. 230 The list of acceptable context_attributes is the same as the list for 231 eglCreateContext. Only when this list of attributes is compatible with those 232 used during context creation will the secondary context be created. 233 This function shall only be called once per secondary context, and must be called 234 before the secondary context is able to be created. Subsequent calls shall 235 return EGL_FALSE and do nothing. 236 237 num_entries shall specify the number of attributes in the list. This number 238 shall prevent accessing memory outside the attribute list, even if EGL_NONE is 239 not yet found in the list. If EGL_NONE is found sooner than this number of 240 attributes list parsing shall stop. 241 242Add the function: 243 244 EGLBoolean eglCompositorSetWindowListEXT (EGLint external_ref_id, 245 const EGLint *external_win_ids, 246 EGLint num_entries); 247 248 This function is called by the primary context to establish the set of 249 all allowable windows associated with a specific secondary context by defining 250 the set of external window identifiers. Window surface creation within secondary 251 contexts use the external window identifier as the native window handle parameter 252 of eglCreateWindowSurface and supply an external reference id as a window creation 253 attribute. 254 Calls to this function when the primary context for the display is not active, 255 shall return EGL_FALSE and do nothing. When this function is successful it 256 shall return EGL_TRUE and associate the list of external window identifiers 257 with the specified secondary context (external_ref_ids). 258 259 external_win_ids shall be an array of user generated integers greater than 1. 260 external window identifiers are unique within the primary EGLContext. Any 261 external window identifier may be associated with multiple secondary contexts 262 however only the first context which calls eglCreateWindowSurface shall 263 successfully create a window surface for the given window. 264 num_entries shall specify the number of external_ref_ids. 265 266Add the function: 267 268 EGLBoolean eglCompositorSetWindowAttributesEXT (EGLint external_win_id, 269 const EGLint *window_attributes, 270 EGLint num_entries); 271 272 This function is called by the primary context to set window specific attributes 273 for the specified external window id. 274 275 The list of valid attributes are: EGL_WIDTH, EGL_HEIGHT, EGL_VERTICAL_RESOLUTION, 276 EGL_HORIZONRAL_RESOLUTION, EGL_PIXEL_ASPECT_RATIO. 277 EGL_WIDTH and EGL_HEIGHT shall set the maximum width and height the secondary 278 context is able to create a window surface with. 279 EGL_VERTICAL_RESOLUTION, EGL_HORIZONTAL_RESOLUTION, and EGL_PIXEL_ASPECT_RATIO 280 shall set the values of these used by the secondary context. 281 Calls to this function when the primary context for the display is not active, 282 shall return EGL_FALSE and do nothing. When this function is successful it 283 shall return EGL_TRUE and associate the list of attributes with the off screen 284 window ID (external_win_id). 285 This function shall only be called once per window, and must be called before 286 the secondary context is able to create the window surface. Subsequent calls 287 shall return EGL_FALSE and do nothing. 288 289 num_entries shall specify the number of attributes in the list. This number 290 shall prevent accessing memory outside the attribute list, even if EGL_NONE is 291 not yet found in the list. If EGL_NONE is found sooner than this number of 292 attributes list parsing shall stop. 293 294Add the function: 295 296 EGLBoolean eglCompositorBindTexWindowEXT (EGLint external_win_id); 297 298 This function is similar to eglBindTexImage in that it binds the windows 299 color buffers to a texture object which can then be composited on the native 300 window by the primary context. This function shall only be callable within 301 the primary context while there is a texture object actively bound by the 302 native rendering API. The function shall return EGL_TRUE if the window is 303 successfully bound to the active texture object. The function shall return 304 EGL_FALSE if binding fails, the context is not the primary context, or the 305 external_win_id is not a valid external window reference as set using 306 eglCompositorSetWindowListEXT. 307 308Add the function: 309 310 EGLBoolean eglCompositorSetSizeEXT(EGLint external_win_id, 311 EGLint width, EGLint height); 312 313 This function shall be called by the primary context to set the width and 314 height of the window. This function returns EGL_FALSE when called by a context 315 other than the primary context. This function will also return EGL_FALSE if 316 the new width and height are larger than the maximums set by 317 eglCompositorSetWindowAttributesEXT. Upon successful window resizing the function 318 shall return EGL_TRUE. 319 Secondary contexts may use EGL to query the windows width and height at runtime 320 to detect window resize events. The window buffer resizing shall be applied 321 to the newly active buffer after the secondary context calls eglSwapBuffers. 322 This will leave an average of 2 buffers which will have to be scaled by the 323 native rendering API to the new resolution. 324 325Add the function: 326 327 EGLBoolean eglCompositorSwapPolicyEXT(EGLint external_win_id, 328 EGLint policy); 329 330 This function shall be called by the primary context to specify the handling 331 of buffer swaps of the context specified by external_ref_id. 332 333 When the policy is set to EGL_COMPOSITOR_DROP_NEWEST_FRAME_EXT, and the 334 secondary context completes a frame by calling eglSwapbuffers, and the 335 primary context is actively reading from the front buffer associated with 336 the external window ID, then the just completed frame is dropped, no buffer 337 swap occurs, and eglSwapBuffers will return EGL_TRUE. 338 If EGL_COMPOSITOR_KEEP_NEWEST_FRAME_EXT is specified and the primary context 339 is actively reading from the front buffer associated with the external window 340 ID then the secondary context's call to eglSwapBuffers will return EGL_FALSE. 341 eglSwapBuffers will continue to return EGL_FALSE as long as the primary context 342 is actively reading from the front buffer. Once the primary context finishes 343 reading from the front buffer the next call to eglSwapBuffers will 344 return EGL_TRUE. It is up to the application to decide if it will wait until 345 eglSwapBuffers returns EGL_TRUE before rendering again. If the secondary 346 context continues to render after eglSwapBuffers returns EGL_FALSE then it will 347 be as if the swap policy was EGL_COMPOSITOR_DROP_NEWEST_FRAME_EXT. 348 349 350Revision History 351 Version 0.1, 30/08/2014 - first draft. 352 Version 0.2, 24/09/2014 second draft. 353 Version 0.3, 21/12/2016 354 Khronos vendor extension clean-up. 355 Version 0.4, 05/01/2016 356 - Change from context and display limitation to context and window limitations 357 - Added additional functions related to external window ids contexts. 358 Version 1.0, 03/02/2017 359 - Fixed misc issues related to parameter names and types. 360 361Question: How are external reference and window IDs assigned and managed? Are they 362 reserved somehow within a new EGL C header file? 363Answer: External IDs are assigned from the software component with the primary 364 context during an EGL initialization stage using eglCompositorSet*ListEXT. 365 The secondary contexts are provided the appropriate external reference ID 366 during end system integration. It is recommended that these values be able 367 to be set via a configuration parameter to the application, to ease 368 integration of multiple programs. 369 370Question: What happens when the secondary contexts render faster than the 371 primary context? 372Answer: This is based on the swap policy set by the compositor, and the rate 373 difference between the render and the compositor. Secondary contexts 374 will be notified by EGL_FALSE being returned if the windows front buffer 375 is currently being read by the compositor. However, if the compositor is 376 not currently reading the front buffer the swap will succeed and the 377 secondary contexts latest rendered frame will now be in the front buffer 378 to be composited. 379 380Question: What happens when the primary context renders faster than the 381 secondary context(s)? 382Answer: The contents of the windows front buffer will be repeated. 383 384Question: Does this infer any Z-ordering for the off-screen surfaces? 385Answer: No, the Z-order is applied by the compositor when doing the final on 386 screen rendering of the off-screen surfaces. Or may be set if a Z-ordering 387 extension is applied to the attribute list of the window using 388 eglCompositorSetWindowAttributesEXT 389 390Comments: 391 392The driver should also have to have enough protection in it to prevent a random 393software component from passing random buffer handles to the driver to prevent 394access to other software components. 395 396The driver may force use of double buffering event if the window surface was created 397using an EGL_RENDER_BUFFER attribute set to EGL_SINGLE_BUFFER. 398 399If EGL_PRIMARY_COMPOSITOR_CONTEXT_EXT is not used to create a context for a specified 400display then EGL will act as though this extension is not enabled. 401