summaryrefslogtreecommitdiff
path: root/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_output_base.txt
diff options
context:
space:
mode:
Diffstat (limited to 'glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_output_base.txt')
-rw-r--r--glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_output_base.txt564
1 files changed, 564 insertions, 0 deletions
diff --git a/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_output_base.txt b/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_output_base.txt
new file mode 100644
index 0000000..1cbd112
--- /dev/null
+++ b/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_output_base.txt
@@ -0,0 +1,564 @@
+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
+
generated by cgit v1.2.3-70-g09d2 (git 2.46.0) at 2025-10-06 01:52:05 +0000