xref: /third_party/openGLES/extensions/ARB/ARB_parallel_shader_compile.txt

Name

    ARB_parallel_shader_compile

Name Strings

    GL_ARB_parallel_shader_compile

Contact

    Timothy Lottes (timothy.lottes 'at' amd.com)

Contributors

    Timothy Lottes, AMD
    Graham Sellers, AMD
    Eric Werness, NVIDIA
    Daniel Koch, NVIDIA

Notice

    Copyright (c) 2015 The Khronos Group Inc. Copyright terms at
        http://www.khronos.org/registry/speccopyright.html

Specification Update Policy

    Khronos-approved extension specifications are updated in response to
    issues and bugs prioritized by the Khronos OpenGL Working Group. For
    extensions which have been promoted to a core Specification, fixes will
    first appear in the latest version of that core Specification, and will
    eventually be backported to the extension document. This policy is
    described in more detail at
        https://www.khronos.org/registry/OpenGL/docs/update_policy.php

Status

    Complete. Approved by the ARB on June 26, 2015.
    Ratified by the Khronos Board of Promoters on August 7, 2015.

Version

    Last Modified Date: 2017-04-24
    Revision: 7

Number

    ARB Extension #179

Dependencies

    This extension is written against OpenGL 4.5 (CoreProfile) dated
    May 28 2015.

Overview

    Compiling GLSL into implementation-specific code can be a time consuming
    process, so a GL implementation may wish to perform the compilation in a
    separate CPU thread. This extension provides a mechanism for the application
    to provide a hint to limit the number of threads it wants to be used to
    compile shaders, as well as a query to determine if the compilation process
    is complete.

New Procedures and Functions

    void MaxShaderCompilerThreadsARB(uint count);

New Tokens

    Accepted by the <pname> parameter of GetBooleanv, GetIntegerv,
    GetInteger64v, GetFloatv, and GetDoublev:

        MAX_SHADER_COMPILER_THREADS_ARB   0x91B0

    Accepted as part of the <pname> parameter to GetShaderiv and
    accepted as part of the <pname> parameter to GetProgramiv:

        COMPLETION_STATUS_ARB             0x91B1

IP Status

    None.

Additions to Chapter 7 "Programs and Shaders",

    Append to the end of 7.1 "Shader Objects",

        Applications may use the following to hint to the driver the maximum
    number background threads it would like to be used in the process of
    compiling shaders or linking programs,

        void MaxShaderCompilerThreadsARB(uint count);

    where <count> is the number of background threads. A <count> of zero
    specifies a request for no parallel compiling or linking and a <count> of
    0xFFFFFFFF requests an implementation-specific maximum.

    An implementation may combine the maximum compiler thread request from
    multiple contexts in a share group in an implementation-specific way.

    An application can query the current MaxShaderCompilerThreadsARB <count>
    by calling GetIntegerv with <pname> set to MAX_SHADER_COMPILER_THREADS_ARB,
    which returns the value of the current state (Table 23.51).


    Add to 7.13 "Shader, Program, and Program Pipeline Queries" under the
    descriptions for "pname" for "GetShaderiv",

        If <pname> is COMPLETION_STATUS_ARB, TRUE is returned if the shader
        compilation has completed, FALSE otherwise.

    Add to 7.13 "Shader, Program, and Program Pipeline Queries" under the
    descriptions for "pname" for "GetProgramiv",

        If <pname> is COMPLETION_STATUS_ARB, TRUE is returned if the program
        linking has completed, FALSE otherwise.

New State

    Add to Table 23.51: Hints
    Get Value                        Type  Get Command   Initial Value  Description           Sec
    -------------------------------  ----  ------------  -------------  --------------------  ----
    MAX_SHADER_COMPILER_THREADS_ARB  Z+    GetIntegerv   0xFFFFFFFF     Max compile threads   7.13

    Add to Table 23.32: Program Object State
    Get Value               Type  Get Command   Initial Value  Description           Sec
    ---------------------   ----  ------------  -------------  --------------------  ----
    COMPLETION_STATUS_ARB   B     GetProgramiv  TRUE           Program linking has   7.13
                                                               completed

    Add to Table 23.30: Shader Object State
    Get Value               Type  Get Command   Initial Value  Description           Sec
    ---------------------   ----  ------------  -------------  --------------------  ----
    COMPLETION_STATUS_ARB   B     GetShaderiv   TRUE           Shader compilation    7.13
                                                               has completed
Issues

    1) Where should the hint state be stored?

    UNRESOLVED: Each context has its own value which may be specified and
    queried, but an implementation may choose to combine the hints from multiple
    contexts in an implmentation-specific manner. There isn't really any
    precedent for per-share group state.

    2) Can we make the requirements more strict?

    RESOLVED: We could, but making sure all of the error behavior is correct and
    fully specified would likely take more time than we have. This spec allows
    an application to clearly request its intent even if there aren't guarantees
    that the implementation will exactly obey the request.

    3) Does glGetIntegerv(MAX_SHADER_COMPILER_THREADS_ARB) just return the
    value set by MaxShaderCompilerThreadsARB? Or, if the state is 0xFFFFFFFF
    ("do something implementation specific"), does it return the number of
    threads the implementation has actually chosen to use?

    RESOLVED: As with other state queries, this returns the value that was last
    set, or if no value was set by the application it returns the default state
    value (0xFFFFFFFF).

Revision History

    Rev  Date        Author    Changes
    ---  ----------  --------  ---------------------------------------------
      1  2015-03-22  tlottes   Initial revision
      2  2015-03-23  tlottes   Added way to get MAX_SHADER_COMPILER_THREADS
      3  2015-04-20  tlottes   Updated tokens and functions
      4  2015-06-18  tlottes   Added New State, noted per context, issues
      5  2016-06-23  ewerness  Clarify the spec is a hint, other language fixes
      6  2015-09-01  pdaniell  Fix the functions that can be used to query
                               MAX_SHADER_COMPILER_THREADS_ARB.
      7  2017-04-24  dgkoch    Spec clarifications, add issue 3.