xref: /third_party/openGLES/extensions/EXT/EXT_debug_label.txt

Name

    EXT_debug_label

Name Strings

    GL_EXT_debug_label

Contributors

    Seth Sowerby
    Benj Lipchak
    Jean-François Roy
    Charles Brissart

Contact

    Benj Lipchak, Apple (lipchak 'at' apple.com)

Status
    
    Complete

Version

    Date: October 7, 2013
    Revision: 4

Number

    OpenGL Extension #439
    OpenGL ES Extension #98

Dependencies
    
    Requires OpenGL ES 1.1.
    
    Written based on the wording of the OpenGL ES 2.0.25 Full Specification
    (November 2, 2010).

    OpenGL ES 1.1 affects the definition of this extension.

    OES_framebuffer_object affects the definition of this extension.
    
    OES_vertex_array_object affects the definition of this extension.

    EXT_occlusion_query_boolean affects the definition of this extension.

    EXT_separate_shader_objects affects the definition of this extension.
    
    OpenGL ES 3.0 affects the definition of this extension.
    
    OpenGL 3.3+ and 4.0+ affect the definition of this extension.

Overview

    This extension defines a mechanism for OpenGL and OpenGL ES applications to 
    label their objects (textures, buffers, shaders, etc.) with a descriptive 
    string. 
    
    When profiling or debugging such an application within a debugger or 
    profiler it is difficult to identify resources from their object names. 
    Even when the resource itself is viewed it can be problematic to 
    differentiate between similar resources. Attaching a label to an object         
    helps obviate this difficulty.
    
    The intended purpose of this is purely to improve the user experience 
    within OpenGL and OpenGL ES development tools.

New Procedures and Functions

    void LabelObjectEXT(enum type, uint object, sizei length, 
        const char *label);
    void GetObjectLabelEXT(enum type, uint object, sizei bufSize, 
        sizei *length, char *label);

New Tokens

    Accepted by the <type> parameter of LabelObjectEXT and 
    GetObjectLabelEXT:

        BUFFER_OBJECT_EXT                              0x9151
        SHADER_OBJECT_EXT                              0x8B48
        PROGRAM_OBJECT_EXT                             0x8B40
        VERTEX_ARRAY_OBJECT_EXT                        0x9154
        QUERY_OBJECT_EXT                               0x9153
        PROGRAM_PIPELINE_OBJECT_EXT                    0x8A4F
        
Additions to Chapter 2 of the OpenGL ES 2.0 Specification (OpenGL Operation)

    None

Additions to Chapter 3 of the OpenGL ES 2.0 Specification (Rasterization)

    None

Additions to Chapter 4 of the OpenGL ES 2.0 Specification (Per-Fragment
Operations and the Framebuffer)

    None

Additions to Chapter 5 of the OpenGL ES 2.0 Specification (Special Functions)

    Add a new section titled Debug Labels

    Debug labels provide a method for annotating an object (texture, buffer, 
    shader, etc.) with a descriptive text label. These labels may then be used 
    by a tool such as a debugger or profiler to describe labeled objects. 
    
    The command
    
        void LabelObjectEXT(enum type, uint object, sizei length, 
            const char *label);
        
    labels the object <object> of type <type> with the label <label>. <length> 
    specifies the length of the string passed in <label>. If <label> is a null-
    terminated string then <length> should not include the terminator. If 
    <length> is 0 and <label> is non-null then <label> is assumed to be null-
    terminated. If <label> is NULL, any debug label is effectively removed from 
    <object>. 

    If <object> is not an object of type <type>, an INVALID_OPERATION error is 
    generated.
    
    A label is part of the state of the object to which it is associated. 
    The initial state of an object's label is NULL. Labels need not be unique.
    
    Values supported for <type> are: TEXTURE, FRAMEBUFFER, RENDERBUFFER,        
    BUFFER_OBJECT_EXT, SHADER_OBJECT_EXT, PROGRAM_OBJECT_EXT,
    VERTEX_ARRAY_OBJECT_EXT, QUERY_OBJECT_EXT, SAMPLER, TRANSFORM_FEEDBACK, and
    PROGRAM_PIPELINE_OBJECT_EXT.
    
Additions to Chapter 6 of the OpenGL ES 2.0 Specification (State and State
Requests)

    Add a new section titled Debug Labels

    The command
    
        void GetObjectLabelEXT(enum type, uint object, sizei bufSize, 
            sizei *length, char *label);

    returns in <label> the string labeling the object <object>. The 
    string <label> will be null terminated. The actual number of characters 
    written into <label>, excluding the null terminator, is returned in 
    <length>. If <length> is NULL, no length is returned. The maximum number 
    of characters that may be written into <label>, including the null
    terminator, is specified by <bufSize>. If no debug label was specified for 
    the object <object> via LabelObjectEXT then <label> will contain an 
    empty string with null terminator and 0 will be returned in <length>. If 
    <label> is NULL and <length> is non-NULL then no string will be returned 
    and the length of the label will be returned in <length>. 
    
    If <object> is not an object of type <type>, an INVALID_OPERATION error is 
    generated.
    
    Values supported for <type> are: TEXTURE, FRAMEBUFFER, RENDERBUFFER,        
    BUFFER_OBJECT_EXT, SHADER_OBJECT_EXT, PROGRAM_OBJECT_EXT, 
    VERTEX_ARRAY_OBJECT_EXT, QUERY_OBJECT_EXT, SAMPLER, TRANSFORM_FEEDBACK, and
    PROGRAM_PIPELINE_OBJECT_EXT.
    
Interactions with OpenGL ES 1.1 and OES_framebuffer_object

    If the GL is OpenGL ES 1.1, mentions of SHADER_OBJECT_EXT and 
    PROGRAM_OBJECT_EXT as types accepted by LabelObjectEXT and 
    GetObjectLabelEXT are omitted.
    
    If OES_framebuffer_object is supported, FRAMEBUFFER and 
    RENDERBUFFER should be replaced by FRAMEBUFFER_OES and RENDERBUFFER_OES, 
    respectively. Otherwise they should be omitted.

Interactions with OpenGL ES 3.0 and OpenGL

    If the GL is not OpenGL ES 3.0 or OpenGL 3.3+, mentions of 
    SAMPLER as a type accepted by LabelObjectEXT and GetObjectLabelEXT are 
    omitted.

    If the GL is not OpenGL ES 3.0 or OpenGL 4.0+, mentions of 
    TRANSFORM_FEEDBACK as a type accepted by LabelObjectEXT and 
    GetObjectLabelEXT are omitted.

Interactions with OES_vertex_array_object

    If OES_vertex_array_object is not available, mentions of 
    VERTEX_ARRAY_OBJECT_EXT as a type accepted by LabelObjectEXT and 
    GetObjectLabelEXT is omitted.

Interactions with EXT_occlusion_query_boolean

    If EXT_occlusion_query_boolean is not available, mentions of 
    QUERY_OBJECT_EXT as a type accepted by LabelObjectEXT and GetObjectLabelEXT
    is omitted.

Interactions with EXT_separate_shader_objects

    If EXT_separate_shader_objects is not available, mentions of 
    PROGRAM_PIPELINE_OBJECT_EXT as a type accepted by LabelObjectEXT and 
    GetObjectLabelEXT is omitted.
    
Errors

    INVALID_OPERATION is generated by LabelObjectEXT or GetObjectLabelEXT 
    if the type of <object> does not match <type>.
    
    INVALID_ENUM error will be generated by LabelObjectEXT or 
    GetObjectLabelEXT if <type> is not one of the allowed object types.
    
    INVALID_VALUE is generated by LabelObjectEXT if <length> is less than
    zero.

    INVALID_VALUE is generated by GetObjectLabelEXT if <bufSize> is less than
    zero.

New State

    Add the following to Table 6.3 Buffer Object State:
    
                                                Initial
    Get Value          Type  Get Cmnd           Value    Description  Sec
    -----------------  ----  -----------------  -------  -----------  ---
    BUFFER_OBJECT_EXT  0*xc  GetObjectLabelEXT  empty    Debug label  5.X

    Add the following to Table 6.8 Textures (state per texture object):
    
                                          Initial
    Get Value  Type  Get Cmnd             Value    Description  Sec
    ---------  ----  -------------------  -------  -----------  ---
    TEXTURE    0*xc  GetObjectLabelEXT    empty    Debug label  5.X

    Add the following to Table 6.14 Shader Object State:
    
                                                Initial
    Get Value          Type  Get Cmnd           Value    Description  Sec
    -----------------  ----  -----------------  -------  -----------  ---
    SHADER_OBJECT_EXT  0*xc  GetObjectLabelEXT  empty    Debug label  5.X

    Add the following to Table 6.15 Program Object State:
    
                                                 Initial
    Get Value           Type  Get Cmnd           Value    Description  Sec
    ------------------  ----  -----------------  -------  -----------  ---
    PROGRAM_OBJECT_EXT  0*xc  GetObjectLabelEXT  empty    Debug label  5.X

    Add the following to Table 6.23 Renderbuffer State:
    
                                             Initial
    Get Value     Type  Get Cmnd             Value    Description  Sec
    ------------  ----  -------------------  -------  -----------  ---
    RENDERBUFFER  0*xc  GetObjectLabelEXT    empty    Debug label  5.X

    Add the following to Table 6.24 Framebuffer State:
    
                                            Initial
    Get Value    Type  Get Cmnd             Value    Description  Sec
    -----------  ----  -------------------  -------  -----------  ---
    FRAMEBUFFER  0*xc  GetObjectLabelEXT    empty    Debug label  5.X

    Add the following to Table 6.VAO Vertex Array Object State:
    
                                                      Initial
    Get Value                Type  Get Cmnd           Value    Description  Sec
    -----------------------  ----  -----------------  -------  -----------  ---
    VERTEX_ARRAY_OBJECT_EXT  0*xc  GetObjectLabelEXT  empty    Debug label  5.X

    Add the following to Table 6.QO Query State:
    
                                               Initial
    Get Value         Type  Get Cmnd           Value    Description  Sec
    ----------------  ----  -----------------  -------  -----------  ---
    QUERY_OBJECT_EXT  0*xc  GetObjectLabelEXT  empty    Debug label  5.X

    Add the following to Table 6.PPO Program Pipeline State:
    
                                                          Init.
    Get Value                    Type  Get Cmnd           Value  Description  Sec
    ---------------------------  ----  -----------------  -----  -----------  ---
    PROGRAM_PIPELINE_OBJECT_EXT  0*xc  GetObjectLabelEXT  empty  Debug label  5.X

    Add the following to Table 6.24 Transform Feedback State:

    Get Value                Type  Get Cmnd           Value    Description  Sec
    -----------------------  ----  -----------------  -------  -----------  ---
    TRANSFORM_FEEDBACK       0*xc  GetObjectLabelEXT  empty    Debug label  5.X

    Add the following to the Table 6.1 Textures (state per sampler object):

    Get Value                Type  Get Cmnd           Value    Description  Sec
    -----------------------  ----  -----------------  -------  -----------  ---
    SAMPLER                  0*xc  GetObjectLabelEXT  empty    Debug label  5.X


New Implementation Dependent State

    None

Issues

    (1) Should labels apply to the currently bound object for the specified 
    type instead of requiring the object name to be specified?
    
    Resolved: No.

    This would require shaders to be attached to a program which was then 
    linked and bound. This may not occur at the time the shader is created 
    and/or compiled. It might require significant work for developers to label 
    their shaders at the point of creation.
    
    (2) Should the extension accept FRAGMENT_SHADER & VERTEX_SHADER 
    instead of SHADER_OBJECT_EXT? ARRAY_BUFFER & ELEMENT_ARRAY_BUFFER instead 
    of BUFFER_OBJECT_EXT?
    
    Resolved: No.
    
    Specifying FRAGMENT_SHADER or VERTEX_SHADER to disambiguate the type of 
    shader would be necessary only if the resolution to issue #1 were yes,
    in which case one would label a shader attached to the currently bound 
    program without explicitly specifying the shader's name.  The same applies
    to buffer objects bound to the current vertex attribute array target versus
    the current element array target.

    (3) Should the extension support printf-style formatting?

    Resolved: No.

    Providing printf-style formatting would impose a much greater burden on the 
    extension in terms of error checking the format string and arguments. 
    Likely all languages capable of calling OpenGL ES have convenient 
    capabilities for formatting strings so it is acceptable to rely on those.
    
    (4) Should labeling a non-existent object effectively create the object?
    
    Resolved: No, since some objects require more information (e.g. a texture
    target) to be properly initialized.
    
Revision History

    Date 06/15/2011
    Revision: 1
       - draft proposal

    Date 07/22/2011
    Revision: 2
       - rename APPLE to EXT, update token names and values

    Date 10/18/2012
    Revision: 3
       - Add OpenGL ES 3.0 interactions: transform feedback and sampler objects
         
    Date 10/07/2013
    Revision: 4
       - Add support for desktop OpenGL