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 is NULL, is ignored and the number of output layers which match is returned in . Otherwise, up to matching layers will be returned in and 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. may be NULL or a list of name/value pairs terminated by EGL_NONE. If no attributes are provided, all output layers associated with 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 and will be unaffected. If is not a valid, initialized EGLDisplay, an EGL_BAD_DISPLAY error is generated. If any name in 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 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 is NULL, is ignored and the number of output ports which match is returned in . Otherwise, up to matching layers will be returned in and 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. may be NULL or a list of name/value pairs terminated by EGL_NONE. If no attributes are provided, all output ports associated with 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 and will be unaffected. If is not a valid, initialized EGLDisplay, an EGL_BAD_DISPLAY error is generated. If any name in 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 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 in . On failure, EGL_FALSE is returned. If is not a valid, initialized EGLDisplay, an EGL_BAD_DISPLAY error is generated. If is not a valid EGLOutputLayerEXT associated with , an EGL_BAD_OUTPUT_LAYER_EXT error is generated. If is not a valid layer attribute name defined in Table 3.10.3.1, an EGL_BAD_ATTRIBUTE error is generated. If 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 . On failure, NULL is returned. If is not a valid, initialized EGLDisplay, an EGL_BAD_DISPLAY error is generated. If is not a valid EGLOutputLayerEXT associated with , an EGL_BAD_OUTPUT_LAYER_EXT error is generated. If is not a valid layer attribute name defined in Table 3.10.3.1, an EGL_BAD_ATTRIBUTE error is generated. If 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 in . On failure, EGL_FALSE is returned. If is not a valid, initialized EGLDisplay, an EGL_BAD_DISPLAY error is generated. If is not a valid EGLOutputPortEXT associated with , an EGL_BAD_OUTPUT_PORT_EXT error is generated. If is not a valid port attribute name defined in Table 3.10.3.2, an EGL_BAD_ATTRIBUTE error is generated. If 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 . On failure, NULL is returned. If is not a valid, initialized EGLDisplay, an EGL_BAD_DISPLAY error is generated. If is not a valid EGLOutputPortEXT associated with , an EGL_BAD_OUTPUT_PORT_EXT error is generated. If is not a valid port attribute name defined in Table 3.10.3.2, an EGL_BAD_ATTRIBUTE error is generated. If 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 to . If 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 is not a valid, initialized EGLDisplay, an EGL_BAD_DISPLAY error is generated. If is not a valid EGLOutputLayerEXT associated with , an EGL_BAD_OUTPUT_LAYER_EXT error is generated. If is not a valid layer attribute name defined in Table 3.10.3.1, an EGL_BAD_ATTRIBUTE error is generated. If 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 to . On failure, EGL_FALSE is returned. If is not a valid, initialized EGLDisplay, an EGL_BAD_DISPLAY error is generated. If is not a valid EGLOutputPortEXT associated with , an EGL_BAD_OUTPUT_PORT_EXT error is generated. If is not a valid port attribute name defined in Table 3.10.3.2, an EGL_BAD_ATTRIBUTE error is generated. If 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