EXT_output_base

Name

EXT_output_base

Name Strings

EGL_EXT_output_base

Contributors

Daniel Kartch
James Jones
Christopher James Halse Rogers

Contacts

Daniel Kartch, NVIDIA (dkartch 'at' nvidia.com)

Status

Complete

Version

Version 9 - August 22, 2014

Number

EGL Extension #78

Extension Type

EGL display extension

Dependencies

Written against the wording of EGL 1.5, plus the EGL_EXT_device_base
specification.

Requires EGL_EXT_device_base

Overview

Increasingly, EGL and its client APIs are being used in place of
"native" rendering APIs to implement the basic graphics
functionality of native windowing systems.  This creates demand
for a method to initialize EGL displays and surfaces directly on
top of native GPU or device objects rather than native window
system objects.  The mechanics of enumerating the underlying
native devices and constructing EGL displays and surfaces from
them have been solved in various platform and implementation-
specific ways.  The EGL device family of extensions offers a
standardized framework for bootstrapping EGL without the use of
any underlying "native" APIs or functionality.

This extension defines new EGL resource types for referencing
display control hardware associated with an EGL device. Its purpose
is to allow rendering to be directed to a screen in the absence of
(or bypassing) a window system. Because the use models for these
resources are potentially diverse, only the objects themselves and
basic functions to acquire and query them are defined here. More
detailed functions and enumerants required to operate on outputs
are provided by separate extensions.

New Types

A handle representing a portion of display control hardware which
accepts a single image as input and processes it for output on a
display device:

    typedef void* EGLOutputLayerEXT;

A handle representing a portion of display control hardware which
transmits a signal to a display device:

    typedef void* EGLOutputPortEXT;

New Functions

EGLBoolean eglGetOutputLayersEXT(
    EGLDisplay dpy,
    const EGLAttrib *attrib_list,
    EGLOutputLayerEXT *layers,
    EGLint max_layers,
    EGLint *num_layers);

EGLBoolean eglGetOutputPortsEXT(
    EGLDisplay dpy,
    const EGLAttrib *attrib_list,
    EGLOutputPortEXT *ports,
    EGLint max_ports,
    EGLint *num_ports);

EGLBoolean eglOutputLayerAttribEXT(
    EGLDisplay         dpy,
    EGLOutputLayerEXT  layer,
    EGLint             attribute,
    EGLAttrib          value);

EGLBoolean eglQueryOutputLayerAttribEXT(
    EGLDisplay         dpy,
    EGLOutputLayerEXT  layer,
    EGLint             attribute,
    EGLAttrib         *value);

const char* eglQueryOutputLayerStringEXT(
    EGLDisplay         dpy,
    EGLOutputLayerEXT  layer,
    EGLint             name);

EGLBoolean eglOutputPortAttribEXT(
    EGLDisplay         dpy,
    EGLOutputPortEXT   port,
    EGLint             attribute,
    EGLAttrib          value);

EGLBoolean eglQueryOutputPortAttribEXT(
    EGLDisplay         dpy,
    EGLOutputPortEXT   port,
    EGLint             attribute,
    EGLAttrib         *value);

const char* eglQueryOutputPortStringEXT(
    EGLDisplay         dpy,
    EGLOutputPortEXT   port,
    EGLint             name);

New Tokens

Functions with a return type of EGLOutputLayerEXT will return this
value on failure:

    EGL_NO_OUTPUT_LAYER_EXT    ((EGLOutputLayerEXT)0)

Functions with a return type of EGLOutputPortEXT will return this
value on failure:

    EGL_NO_OUTPUT_PORT_EXT     ((EGLOutputPortEXT)0)

Functions which fail due to a bad EGLOutputLayerEXT handle will set
this error code:

    EGL_BAD_OUTPUT_LAYER_EXT   0x322D

Functions which fail due to a bad EGLOutputPortEXT handle will set
this error code:

    EGL_BAD_OUTPUT_PORT_EXT    0x322E

Functions which set or query the swap interval use this attribute
name:

    EGL_SWAP_INTERVAL_EXT      0x322F

Add a new section "2.1.4 Outputs" after "2.1.3 Displays":

An EGLDisplay may have zero or more associated EGLOutputLayerEXT
and EGLOutputPortEXT objects.  These represent, respectively, the
inputs and outputs of display control hardware.

An EGLOutputLayerEXT is an abstract handle representing an element
of display control hardware which receives image data and processes
it for display. This processing is hardware-dependent, and may
include, but is not limited to, color space transformation, scaling
and rotation, and composition/blending with images from other
EGLOutputLayerEXTs. 

An EGLOutputPortEXT is an abstract handle representing an element of
display control hardware which sends a signal to drive a display
screen. In general, this signal is the result of the processing of
one or more EGLOutputLayerEXTs. 

Add new entries to section "3.1 Errors":

EGL_BAD_OUTPUT_LAYER_EXT
    An EGLOutputLayerEXT argument does not name a valid
    EGLOutputLayerEXT. Any command taking an EGLOutputLayerEXT
    parameter may generate this error.

EGL_BAD_OUTPUT_PORT_EXT
    An EGLOutputPortEXT argument does not name a valid
    EGLOutputPortEXT. Any command taking an EGLOutputPortEXT
    parameter may generate this error.

Add a new section "3.10 Device Outputs" after "3.9 Posting the Color Buffer":

3.10 Device Outputs

A simple platform running a custom software suite may not require a
formal window system. Instead, individual applications or a
compositor may send rendering results directly to display control
hardware, represented by EGLOutputLayerEXT and EGLOutputPortEXT
handles.

As with other EGL resources, EGLOutputLayerEXT and EGLOutputPortEXT
handles are owned by an EGLDisplay, but not all EGLDisplays are
required to support these objects. In general, they will only be
available for EGLDisplays obtained from platforms which allow direct
manipulation of display devices.

3.10.1 Acquiring Outputs

To obtain EGLOutputLayerEXT handles associated with a display which
match a list of attributes, use

    EGLBoolean eglGetOutputLayersEXT(
        EGLDisplay dpy,
        const EGLAttrib *attrib_list,
        EGLOutputLayerEXT *layers,
        EGLint max_layers,
        EGLint *num_layers)

On success, EGL_TRUE is returned. If <layers> is NULL, <max_layers>
is ignored and the number of output layers which match <attrib_list>
is returned in <num_layers>. Otherwise, up to <max_layers> matching
layers will be returned in <layers> and <num_layers> will be set to
the number of layer handles returned. The states of the output
layers are not altered by this query, and output layer handles can
be retrieved by multiple calls to this function.

<attrib_list> may be NULL or a list of name/value pairs terminated
by EGL_NONE. If no attributes are provided, all output layers
associated with <dpy> will match. Otherwise, only those layers
matching all attributes provided in the list will be returned,
unless the value specified is EGL_DONT_CARE. If there are no
matching layers but all parameters are otherwise valid, success is
returned but num_layers is set to 0.

On failure, EGL_FALSE will be returned and the memory referenced by
<layers> and <num_layers> will be unaffected. If <dpy> is not a
valid, initialized EGLDisplay, an EGL_BAD_DISPLAY error is
generated. If any name in <attrib_list> is not a valid layer
attribute name defined in Table 3.10.3.1, an EGL_BAD_ATTRIBUTE error
is generated. If any name in <attrib_list> does not allow search
access, an EGL_BAD_ACCESS error is generated.

To obtain EGLOutputPortEXT handles associated with a display which
match a list of attributes, use

    EGLBoolean eglGetOutputPortsEXT(
        EGLDisplay dpy,
        const EGLAttrib *attrib_list,
        EGLOutputPortEXT *ports,
        EGLint max_ports,
        EGLint *num_ports)

On success, EGL_TRUE is returned. If <ports> is NULL, <max_ports> is
ignored and the number of output ports which match <attrib_list> is
returned in <num_ports>. Otherwise, up to <max_ports> matching
layers will be returned in <ports> and <num_ports> will be set to
the number of port handles returned. The states of the output ports
are not altered by this query, and output port handles can be
retrieved by multiple calls to this function.

<attrib_list> may be NULL or a list of name/value pairs terminated
by EGL_NONE. If no attributes are provided, all output ports
associated with <dpy> will match. Otherwise, only those ports
matching all attributes provided in the list will be returned,
unless the value specified is EGL_DONT_CARE. If there are no
matching ports but all parameters are otherwise valid, success is
returned but num_ports is set to 0.

On failure, EGL_FALSE will be returned and the memory referenced by
<ports> and <num_ports> will be unaffected. If <dpy> is not a valid,
initialized EGLDisplay, an EGL_BAD_DISPLAY error is generated. If
any name in <attrib_list> is not a valid port attribute name defined
in Table 3.10.3.2, an EGL_BAD_ATTRIBUTE error is generated. If any
name in <attrib_list> does not allow search access, an
EGL_BAD_ACCESS error is generated.

3.10.2 Lifetime of Output Handles

An initialized EGLDisplay has a fixed set of output layer and port
resources available. Implementations may defer creation of handles
and allocation of data structions for these objects until they are
first requested. However, once acquired, they remain valid as long
as the EGLDisplay is not terminated.

3.10.3 Output Attributes

Valid attributes associated with output layers and ports are listed
in Tables 3.10.3.1 and 3.10.3.2, respectively. Additional attributes
may be defined by other extensions. The Access columns contain one
or more of the letters "S", "R", and W". A value of "S" indicates
the attribute may be used to restrict the search when obtaining a
list of output handles. A value of "R" indicates the value may be
queried from an output handle. A value of "W" indicates the value
may be modified using an output handle.

    Attribute               Type      Access
    ---------------------   -------   ------
    EGL_SWAP_INTERVAL_EXT   integer   R|W
    EGL_MIN_SWAP_INTERVAL   integer   R
    EGL_MAX_SWAP_INTERVAL   integer   R

    Table 3.10.3.1 Output layer attributes

    Attribute               Type      Access
    ---------------------   -------   ------
    [no attributes supported]

    Table 3.10.3.2 Output port attributes

3.10.3.1 Querying Output Attributes

To query attributes of an EGLOutputLayerEXT, use

    EGLBoolean eglQueryOutputLayerAttribEXT(
        EGLDisplay         dpy,
        EGLOutputLayerEXT  layer,
        EGLint             attribute,
        EGLAttrib         *value)

On success, this function returns EGL_TRUE and stores the value of
<attribute> in <value>.
   
On failure, EGL_FALSE is returned. If <dpy> is not a valid,
initialized EGLDisplay, an EGL_BAD_DISPLAY error is generated. If
<layer> is not a valid EGLOutputLayerEXT associated with <dpy>, an
EGL_BAD_OUTPUT_LAYER_EXT error is generated. If <attribute> is not a
valid layer attribute name defined in Table 3.10.3.1, an
EGL_BAD_ATTRIBUTE error is generated. If <attribute> has string
type or does not allow read access, an EGL_BAD_ACCESS error is
generated.

To query string properties of an EGLOutputLayerEXT, use

    const char* eglQueryOutputLayerStringEXT(
        EGLDisplay         dpy,
        EGLOutputLayerEXT  layer,
        EGLint             attribute)

On success, this function returns a zero-terminated string
containing the value associated with <name>.

On failure, NULL is returned. If <dpy> is not a valid, initialized
EGLDisplay, an EGL_BAD_DISPLAY error is generated. If <layer> is not
a valid EGLOutputLayerEXT associated with <dpy>, an
EGL_BAD_OUTPUT_LAYER_EXT error is generated. If <name> is not a
valid layer attribute name defined in Table 3.10.3.1, an
EGL_BAD_ATTRIBUTE error is generated. If <attribute> has non-string
type or does not allow read access, an EGL_BAD_ACCESS error is
generated.

To query attributes of an EGLOutputPortEXT, use

    EGLBoolean eglQueryOutputPortAttribEXT(
        EGLDisplay         dpy,
        EGLOutputPortEXT   port,
        EGLint             attribute,
        EGLAttrib         *value)

On success, this function returns EGL_TRUE and stores the value of
<attribute> in <value>.
   
On failure, EGL_FALSE is returned. If <dpy> is not a valid,
initialized EGLDisplay, an EGL_BAD_DISPLAY error is generated. If
<port> is not a valid EGLOutputPortEXT associated with <dpy>, an
EGL_BAD_OUTPUT_PORT_EXT error is generated. If <attribute> is not a
valid port attribute name defined in Table 3.10.3.2, an
EGL_BAD_ATTRIBUTE error is generated. If <attribute> has string
type or does not allow read access, an EGL_BAD_ACCESS error is
generated.

To query string properties of an EGLOutputPortEXT, use

    const char* eglQueryOutputPortStringEXT(
        EGLDisplay         dpy,
        EGLOutputPortEXT   port,
        EGLint             attribute)

On success, this function returns a zero-terminated string
containing the value associated with <name>.

On failure, NULL is returned. If <dpy> is not a valid, initialized
EGLDisplay, an EGL_BAD_DISPLAY error is generated. If <port> is not
a valid EGLOutputPortEXT associated with <dpy>, an
EGL_BAD_OUTPUT_PORT_EXT error is generated. If <name> is not a
valid port attribute name defined in Table 3.10.3.2, an
EGL_BAD_ATTRIBUTE error is generated. If <attribute> has non-string
type or does not allow read access, an EGL_BAD_ACCESS error is
generated.

3.10.3.2 Setting Output Attributes

To set attributes of an EGLOutputLayerEXT, use

    EGLBoolean eglOutputLayerAttribEXT(
        EGLDisplay         dpy,
        EGLOutputLayerEXT  layer,
        EGLint             attribute,
        EGLAttrib          value)

On success, this function returns EGL_TRUE and sets the value of
<attribute> to <value>.
   
If <attribute> is EGL_SWAP_INTERVAL_EXT, the value provided will be
silently clamped to the range specified by the layer's
EGL_MIN_SWAP_INTERVAL and EGL_MAX_SWAP_INTERVAL values.
   
On failure, EGL_FALSE is returned. If <dpy> is not a valid,
initialized EGLDisplay, an EGL_BAD_DISPLAY error is generated. If
<layer> is not a valid EGLOutputLayerEXT associated with <dpy>, an
EGL_BAD_OUTPUT_LAYER_EXT error is generated. If <attribute> is not a
valid layer attribute name defined in Table 3.10.3.1, an
EGL_BAD_ATTRIBUTE error is generated. If <attribute> does not
allow write access, an EGL_BAD_ACCESS error is generated.

To set attributes of an EGLOutputPortEXT, use

    EGLBoolean eglOutputPortAttribEXT(
        EGLDisplay         dpy,
        EGLOutputPortEXT   port,
        EGLint             attribute,
        EGLAttrib          value)

On success, this function returns EGL_TRUE and sets the value of
<attribute> to <value>.

On failure, EGL_FALSE is returned. If <dpy> is not a valid,
initialized EGLDisplay, an EGL_BAD_DISPLAY error is generated. If
<port> is not a valid EGLOutputPortEXT associated with <dpy>, an
EGL_BAD_OUTPUT_PORT_EXT error is generated. If <attribute> is not a
valid port attribute name defined in Table 3.10.3.2, an
EGL_BAD_ATTRIBUTE error is generated. If <attribute> does not
allow write access, an EGL_BAD_ACCESS error is generated.

3.10.4 Setting Output Modes

EGL does not currently define any mechanims to adjust display
modes through EGLOutputPortEXTs. These may be added via additional
extensions.

3.10.5 Posting to Outputs

EGL does not currently define any mechanisms to post rendering
results to EGLOutputsLayerEXTs. These may be added via additional
extensions. However, unless otherwise specified, such mechanims
will respect the layer's EGL_SWAP_INTERVAL_EXT value, which
specifies the minimum number of video frame periods for which the
frames should be displayed, in a manner analogous to using
eglSwapInterval for the current draw surface. The default value of
EGL_SWAP_INTERVAL_EXT is 1, clamped to the layer's 
EGL_MIN_SWAP_INTERVAL and EGL_MAX_SWAP_INTERVAL values.

(Example: See extension specification
EGL_EXT_stream_consumer_egloutput)

Issues

1.  Should this extension provide a mechanism to enumerate outputs
    associated with an EGLDevice and set their modes?

    RESOLVED: No. On many operating systems there already exist
    standardized and/or widely accepted low level mechanisms for
    performing these tasks. Duplicating this support in EGL would
    impose an undesirable implementation burden where output handles
    are only required as a means to direct rendering to a display
    screen. Functions for enumerating screens or obtaining them from
    platform-dependent representations will be provided by other
    extensions.

2.  Should output layer and port handles be associated with an
    EGLDisplay, or vice versa?

    RESOLVED: Yes. Furthermore, it may only be possible to obtain
    output handles from some EGLDisplays. The primary intended use
    case is the EGLDisplay associated with an EGLDevice, through the
    platform defined by EGL_EXT_platform_device. This represents raw
    device access available in the absence of a window system.
    EGLDisplays associated with other platforms typically represent
    handles provided by window systems, which may not allow direct
    access to the display control hardware.

3.  Can the EGLDeviceEXT handle be returned by a query function
    which returns integer attributes?

    RESOLVED: Yes. Function definition has been updated to use
    EGLAttribEXT, which is compatible with EGL handles.

4.  What display mode properties should be queriable by the base
    extension? Does the application require width/height/refresh or
    should those be left to other mechanisms or additional
    extensions? If hardware supports selecting a portion of the
    image for display, or restricting an image to a portion of the
    screen, or scaling an image to a different resolution for
    display, should all these settings be queriable?

    RESOLVED: The base extension will not define any display
    properties. These will be left to future extensions if required.

5.  How should stereo/multiview displays be handled? Should all
    views share a single output or does each one have its own?

    UNRESOLVED.  Left for a future extension to define.

6.  This extension is currently focused on individual display layers
    for the purpose of directing rendering output. An API covering
    all hardware would associate one or more of those layers with a
    display port. Do we need to abstract both?

    RESOLVED: Yes. Extension has been modified to abstract both
    inputs (layers) and outputs (ports) of display control hardware.
    An implementation is not required to return any ports in the
    query function if it provides no means to operate on them.

Revision History:

#9  (August 22nd, 2014) James Jones
    - Marked complete.
    - Added minor coments to issue 5.
    - Listed Daniel as the contact.

#8  (June 10th, 2014) Daniel Kartch
    - Fixed prototypes for layer/port attribute setting functions.

#7  (June 5th, 2014) Daniel Kartch
    - Assigned enumerated values for constants.
    - Indicated default swap interval value.

#6  (May 28th, 2014) Daniel Kartch
    - Updated wording based on EGL 1.5 specification, using
      EGLAttrib instead of EGLAttribEXT.
    - Added functions to set layer and port attributes.
    - Added table of valid attributes, with min/max/current swap
      interval values, and adjusted function descriptions
      accordingly.
    - Refined description for output enumeration functions to better
      indicate the effect of attribute list.
    - Added effect of swap interval in posting section.

#5  (January 31st, 2014) Daniel Kartch
    - Added eglGetOutput* functions, folding in and generalizing
      functionality previously provided by EXT_native_output
      extension.
    - Separated descriptions for layer and port query functions for
      clarity.

#4  (January 22nd, 2014) Daniel Kartch
    - Added section clarifying that this extension provides no means
      to use output ports to set display modes, but future
      extensions may.

#3  (January 17th, 2014) Daniel Kartch
    - Updated names of example extension for obtaining and using
      output handles.
    - Fixed typos.

#2  (November 12th, 2013) Daniel Kartch
    - Replaced EGLOutput with EGLOutputLayer and added
      EGLOutputPort (and modified/added corresponding functions), to
      allow both inputs and outputs of display control hardware to
      be abstracted.
    - Modified attribute query functions to use EGLAttribEXT and
      added string query functions.
    - Removed display mode attributes. These can be defined by a
      separate extension if desired.
    - Removed destructor function for outputs and added section on
      lifetime, as well as language describing their relationship to
      EGLDisplays.

#1  (October 25nd, 2013) Daniel Kartch
    - Initial draft