xref: /third_party/EGL/extensions/EXT/EGL_EXT_compositor.txt

Name

  EXT_compositor

Name Strings

  EGL_EXT_compositor

Contributors

  Marc Moody
  Daniel Herring

Contacts
  
  Marc Moody, Boeing Inc., marc dot d dot moody at boeing dot com
  Daniel Herring, Core Avionics & Industrial Inc., daniel dot herring at ch1group dot com

Status

  Complete

Version
  Version 1.0, February 3, 2017

Number

  EGL Extension #116

Dependencies

  Requires EGL 1.0.

  This extension is written against the wording of the EGL 1.4
  Specification - April 6, 2011, but may be implemented against earlier
  versions.

Overview

  This extension allows for the composition of multiple windows within
  a multi-partition EGL system. The extension allows a primary EGLContext and
  window to be created for each display. All other windows are created using
  non-displayable surfaces. A handle to each off-screen window is provided
  to the primary EGLContext to allow the composition of all non-displayable windows
  on a single display.

  For each display, there is one EGLContext which has access to create on screen
  windows, this is call the primary context for this display. All other EGLContexts
  are referred to as secondary contexts.

  This extension requires a multi-partition EGL driver to support asynchronous
  rendering of off screen surfaces.

  Information assurance is provided by preventing context and surface creation by
  unregistered contexts and by preventing the non-primary contexts and surfaces
  from rendering to the display.

New Types

  None

New Procedures and Functions

  EGLBoolean eglCompositorSetContextListEXT (const EGLint *external_ref_ids,
                                                EGLint num_entries);

  EGLBoolean eglCompositorSetContextAttributesEXT (EGLint external_ref_id,
                                       const EGLint *context_attributes,
                                       EGLint num_entries);

  EGLBoolean eglCompositorSetWindowListEXT (EGLint external_ref_id,
                                        const EGLint *external_win_ids,
                                        EGLint num_entries);

  EGLBoolean eglCompositorSetWindowAttributesEXT (EGLint external_win_id,
                                       const EGLint *window_attributes,
                                       EGLint num_entries);

  EGLBoolean eglCompositorBindTexWindowEXT (EGLint external_win_id);

  EGLBoolean eglCompositorSetSizeEXT (EGLint external_win_id,
                                      EGLint width, EGLint height);

  EGLBoolean eglCompositorSwapPolicyEXT (EGLint external_win_id,
                                              EGLint policy);


New Tokens

  New attributes accepted by the <attrib_list> argument of
  eglCreateContext:

    EGL_PRIMARY_COMPOSITOR_CONTEXT_EXT     0x3460

  New attributes accepted by the <attrib_list> argument of
  eglCreateContext and eglCreateWindowSurface:

    EGL_EXTERNAL_REF_ID_EXT                0x3461

  New attributes accepted by the <policy> argument of
  eglCompositorSwapPolicyHint:

    EGL_COMPOSITOR_DROP_NEWEST_FRAME_EXT   0x3462

    EGL_COMPOSITOR_KEEP_NEWEST_FRAME_EXT   0x3463

Modify Section 3.7.1 of the EGL 1.4 Specification, paragraph 2
 (Creating Rendering Contexts) on pg. 43
  From:
  If eglCreateContext succeeds, it initializes the context to the initial state defined
  for the current rendering API, and returns a handle to it. The context can be
  used to render to any compatible EGLSurface.

  To:
  If eglCreateContext succeeds, it initializes the context to the initial state defined
  for the current rendering API, and returns a handle to it. The context can be
  used to render to any compatible off-screen rendering surface (Sections 3.5.2
  and 3.5.4). A secondary context can be used to render to compatible window surfaces
  which have been associated with the context using eglCompositorSetWindowListEXT. A
  non-secondary context can be used to render to any compatible EGLSurface.

Modify Section 3.7.1 of EGL 1.4 Specification, paragraph 5
 (Creating Rendering Contexts) on pg. 43
  From:
  attrib_list specifies a list of attributes for the context. The list has the same
  structure as described for eglChooseConfig. The only attribute that can be specified
  in attrib_list is EGL_CONTEXT_CLIENT_VERSION, and this attribute may only
  be specified when creating a OpenGL ES context (e.g. when the current rendering
  API is EGL_OPENGL_ES_API).

  To:
  attrib_list specifies a list of attributes for the context. The list has the same
  structure as described for eglChooseConfig. The attributes that can be specified
  in attrib_list are EGL_CONTEXT_CLIENT_VERSION, EGL_PRIMARY_COMPOSITOR_CONTEXT_EXT,
  EGL_EXTERNAL_REF_ID_EXT.

Modify Section 3.7.1 of EGL 1.4 Specification, paragraph 7
 (Creating Rendering Contexts) on pg. 43
  From:
  EGL_CONTEXT_CLIENT_VERSION determines which version of an OpenGL
  ES context to create. An attribute value of 1 specifies creation of an OpenGL ES
  1.x context. An attribute value of 2 specifies creation of an OpenGL ES 2.x context.
  The default value for EGL_CONTEXT_CLIENT_VERSION is 1.

  To:
  EGL_CONTEXT_CLIENT_VERSION determines which version of an OpenGL
  ES context to create. An attribute value of 1 specifies creation of an OpenGL ES
  1.x context. An attribute value of 2 specifies creation of an OpenGL ES 2.x context.
  The default value for EGL_CONTEXT_CLIENT_VERSION is 1. EGL_CONTEXT_CLIENT_VERSION
  may only be specified when creating a OpenGL ES context (e.g. when the current
  rendering API is EGL_OPENGL_ES_API).

Additions to Section 3.7.1 of the EGL 1.4 Specification (Creating Rendering Contexts).

  The first call to eglCreateContext with EGL_PRIMARY_COMPOSITOR_CONTEXT_EXT
  set as EGL_TRUE in the <attrib-list> returns an EGLContext handle which will
  act as the primary context for the specified EGLDisplay. This shall be the
  only context on this EGLDisplay which is able to be bound to an on-screen window
  on the EGLDisplay. Subsequent calls to eglCreateContext, for the same display,
  in any address space with EGL_PRIMIARY_COMPOSITOR_CONTEXT_EXT set as EGL_TRUE
  shall return EGL_NO_CONTEXT.
  Subsequent calls, in any address space for the same display, to eglCreateContext
  which do not use EGL_PRIMARY_COMPOSITOR_CONTEXT_EXT should use the the attribute
  EGL_EXTERNAL_REF_ID_EXT and an external reference identifier to create a valid
  EGLContext.
  Subsequent calls, in any address space for the same display, to eglCreateContext
  which do not use EGL_PRIMARY_COMPOSITOR_CONTEXT_EXT and do not use
  EGL_EXTERNAL_REF_ID_EXT shall not create a context and shall return
  EGL_NO_CONTEXT and set the error EGL_BAD_ACCESS.

  EGL_PRIMARY_COMPOSITOR_CONTEXT_EXT notifies EGL that this context is the only
  context allowed to render to a on screen window surface for this display. This
  attribute is followed in the attribute list by either EGL_TRUE or EGL_FALSE.
  EGL_EXTERNAL_REF_ID_EXT is followed by an external reference identifier which
  associates this context with the list of allowed contexts set by
  eglCompositorSetContextListEXT. If the reference identifier has already been
  used to initiate another call to eglCreateContext in any address space, this
  call shall fail and set the error EGL_BAD_ATTRIBUTE. IF the external reference
  identifier is not a valid identifier the error EGL_BAD_ATTRIBUTE shall be set
  and the call shall fail. If this attribute is set and the primary context has
  not yet been created then the error EGL_BAD_MATCH and the call shall fail.

  Only when the attributes specified via attrib_list and those specified for this
  context using eglCompositorSetContextAttributesEXT are compatible will the
  context be successfully created.

Modify the list of parameters supported by eglCreateWindowSurface in section 3.5.1
 (Creating On-Screen Rendering Surfaces) on p. 27:

  An external window identifier (EGLuint external_win_id) is associated with
  each off screen window. EGLNativeWindowType shall be EGLint and the
  external window identifier shall be used as the value for the <win> parameter.
  EGL_EXTERNAL_REF_ID_EXT with the context external reference id shall be in the
  attrib_list. If the external window identifier and the external reference identifier
  do not match a pair set using eglCompositorSetWindowListEXT window creation shall
  fail.

Add the function: 

  EGLBoolean eglCompositorSetContextListEXT(const EGLint *external_ref_ids,
                                            EGLint num_entries);

    This function is called by the primary context to establish the set of
    all allowable secondary contexts by defining the set of external reference
    identifiers. Secondary contexts shall identify their external reference
    identifier by setting the EGL_EXTERNAL_REF_ID_EXT attribute when calling
    eglCreateContext.
    Calls to this function when the primary context for the display is not active,
    shall return EGL_FALSE and do nothing. When this function is successful it
    shall return EGL_TRUE and associate the list of external reference identifiers
    with the active display.
    This function shall only be called once per primary context. Subsequent calls
    shall return EGL_FALSE and do nothing.

    external_ref_ids shall be an array of user generated integers greater than 1.
    num_entries shall specify the number of external_ref_ids.

Add the function:

  EGLBoolean eglCompositorSetContextAttributesEXT (EGLint external_ref_id,
                                     const EGLint *context_attributes,
                                     EGLint num_entries);

    This function is called by the primary context to establish a list of compatible
    context attributes.
    Calls to this function when the primary context for the display is not active
    shall return EGL_FALSE and do nothing. When the function is successful it shall
    return EGL_TRUE and associate the given attributes to the subsequent
    eglCreateContext call using the given external reference id.
    The list of acceptable context_attributes is the same as the list for
    eglCreateContext. Only when this list of attributes is compatible with those
    used during context creation will the secondary context be created.
    This function shall only be called once per secondary context, and must be called
    before the secondary context is able to be created. Subsequent calls shall
    return EGL_FALSE and do nothing.

    num_entries shall specify the number of attributes in the list. This number
     shall prevent accessing memory outside the attribute list, even if EGL_NONE is
     not yet found in the list. If EGL_NONE is found sooner than this number of
     attributes list parsing shall stop.

Add the function:

  EGLBoolean eglCompositorSetWindowListEXT (EGLint external_ref_id,
                                      const EGLint *external_win_ids,
                                      EGLint num_entries);

    This function is called by the primary context to establish the set of
    all allowable windows associated with a specific secondary context by defining
    the set of external window identifiers. Window surface creation within secondary
    contexts use the external window identifier as the native window handle parameter
    of eglCreateWindowSurface and supply an external reference id as a window creation
    attribute.
    Calls to this function when the primary context for the display is not active,
    shall return EGL_FALSE and do nothing. When this function is successful it
    shall return EGL_TRUE and associate the list of external window identifiers
    with the specified secondary context (external_ref_ids).

    external_win_ids shall be an array of user generated integers greater than 1.
     external window identifiers are unique within the primary EGLContext. Any
     external window identifier may be associated with multiple secondary contexts
     however only the first context which calls eglCreateWindowSurface shall
     successfully create a window surface for the given window.
    num_entries shall specify the number of external_ref_ids.

Add the function:

  EGLBoolean eglCompositorSetWindowAttributesEXT (EGLint external_win_id,
                                     const EGLint *window_attributes,
                                     EGLint num_entries);

    This function is called by the primary context to set window specific attributes
    for the specified external window id.

    The list of valid attributes are: EGL_WIDTH, EGL_HEIGHT, EGL_VERTICAL_RESOLUTION,
    EGL_HORIZONRAL_RESOLUTION, EGL_PIXEL_ASPECT_RATIO.
    EGL_WIDTH and EGL_HEIGHT shall set the maximum width and height the secondary
    context is able to create a window surface with.
    EGL_VERTICAL_RESOLUTION, EGL_HORIZONTAL_RESOLUTION, and EGL_PIXEL_ASPECT_RATIO
    shall set the values of these used by the secondary context.
    Calls to this function when the primary context for the display is not active,
    shall return EGL_FALSE and do nothing. When this function is successful it
    shall return EGL_TRUE and associate the list of attributes with the off screen
    window ID (external_win_id).
    This function shall only be called once per window, and must be called before
    the secondary context is able to create the window surface. Subsequent calls
    shall return EGL_FALSE and do nothing.

    num_entries shall specify the number of attributes in the list. This number
    shall prevent accessing memory outside the attribute list, even if EGL_NONE is
    not yet found in the list. If EGL_NONE is found sooner than this number of
    attributes list parsing shall stop.

Add the function:

  EGLBoolean eglCompositorBindTexWindowEXT (EGLint external_win_id);

    This function is similar to eglBindTexImage in that it binds the windows
    color buffers to a texture object which can then be composited on the native
    window by the primary context. This function shall only be callable within
    the primary context while there is a texture object actively bound by the
    native rendering API. The function shall return EGL_TRUE if the window is
    successfully bound to the active texture object. The function shall return
    EGL_FALSE if binding fails, the context is not the primary context, or the
    external_win_id is not a valid external window reference as set using
    eglCompositorSetWindowListEXT.

Add the function:

  EGLBoolean eglCompositorSetSizeEXT(EGLint external_win_id,
                                         EGLint width, EGLint height);

    This function shall be called by the primary context to set the width and
    height of the window. This function returns EGL_FALSE when called by a context
    other than the primary context. This function will also return EGL_FALSE if
    the new width and height are larger than the maximums set by
    eglCompositorSetWindowAttributesEXT. Upon successful window resizing the function
    shall return EGL_TRUE.
    Secondary contexts may use EGL to query the windows width and height at runtime
    to detect window resize events. The window buffer resizing shall be applied
    to the newly active buffer after the secondary context calls eglSwapBuffers.
    This will leave an average of 2 buffers which will have to be scaled by the
    native rendering API to the new resolution.

Add the function:

  EGLBoolean eglCompositorSwapPolicyEXT(EGLint external_win_id,
                                             EGLint policy);

    This function shall be called by the primary context to specify the handling
    of buffer swaps of the context specified by external_ref_id.

    When the policy is set to EGL_COMPOSITOR_DROP_NEWEST_FRAME_EXT, and the
    secondary context completes a frame by calling eglSwapbuffers, and the
    primary context is actively reading from the front buffer associated with
    the external window ID, then the just completed frame is dropped, no buffer
    swap occurs, and eglSwapBuffers will return EGL_TRUE.
    If EGL_COMPOSITOR_KEEP_NEWEST_FRAME_EXT is specified and the primary context
    is actively reading from the front buffer associated with the external window
    ID then the secondary context's call to eglSwapBuffers will return EGL_FALSE.
    eglSwapBuffers will continue to return EGL_FALSE as long as the primary context
    is actively reading from the front buffer. Once the primary context finishes
    reading from the front buffer the next call to eglSwapBuffers will
    return EGL_TRUE. It is up to the application to decide if it will wait until
    eglSwapBuffers returns EGL_TRUE before rendering again. If the secondary
    context continues to render after eglSwapBuffers returns EGL_FALSE then it will
    be as if the swap policy was EGL_COMPOSITOR_DROP_NEWEST_FRAME_EXT.


Revision History
  Version 0.1, 30/08/2014 - first draft.
  Version 0.2, 24/09/2014  second draft.
  Version 0.3, 21/12/2016
     Khronos vendor extension clean-up.
  Version 0.4, 05/01/2016
   - Change from context and display limitation to context and window limitations
   - Added additional functions related to external window ids contexts.
  Version 1.0, 03/02/2017
   - Fixed misc issues related to parameter names and types. 

Question: How are external reference and window IDs assigned and managed? Are they
          reserved somehow within a new EGL C header file?
Answer:   External IDs are assigned from the software component with the primary
          context during an EGL initialization stage using eglCompositorSet*ListEXT.
          The secondary contexts are provided the appropriate external reference ID
          during end system integration. It is recommended that these values be able
          to be set via a configuration parameter to the application, to ease 
          integration of multiple programs.

Question: What happens when the secondary contexts render faster than the
          primary context?
Answer:   This is based on the swap policy set by the compositor, and the rate
          difference between the render and the compositor. Secondary contexts
          will be notified by EGL_FALSE being returned if the windows front buffer
          is currently being read by the compositor. However, if the compositor is
          not currently reading the front buffer the swap will succeed and the
          secondary contexts latest rendered frame will now be in the front buffer
          to be composited.

Question: What happens when the primary context renders faster than the
          secondary context(s)?
Answer:   The contents of the windows front buffer will be repeated.

Question: Does this infer any Z-ordering for the off-screen surfaces?
Answer:   No, the Z-order is applied by the compositor when doing the final on
          screen rendering of the off-screen surfaces. Or may be set if a Z-ordering
          extension is applied to the attribute list of the window using
          eglCompositorSetWindowAttributesEXT

Comments: 

The driver should also have to have enough protection in it to prevent a random
software component from passing random buffer handles to the driver to prevent
access to other software components.

The driver may force use of double buffering event if the window surface was created
using an EGL_RENDER_BUFFER attribute set to EGL_SINGLE_BUFFER.

If EGL_PRIMARY_COMPOSITOR_CONTEXT_EXT is not used to create a context for a specified
display then EGL will act as though this extension is not enabled.