| 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 |
| |
