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
