xref: /third_party/EGL/extensions/EXT/EGL_EXT_output_base.txt

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