glslang/Todo.txt

Current functionality level: ESSL 3.0

Link Validation
    + provide input config file for setting limits
	  - also consider spitting out measures of complexity
    + ensure no static references thrown away
    Cross-stage linking
      - type consistency check of uniform and ins <-> outs, both variables and blocks, stage-specific arrayness matching
      - location/binding/index check
      - matching initializers for uniforms
      - mixed es/non-es profiles
      - statically consumed input not produced by previous stage
      - matching between gl_PerVertex blocks and gl_PerFragment blocks
      - compute shader not with other stages
      - 1.3: deprecated mixing fixed vertex/fragment stage with programmable fragment/vertex stage.
      - 4.3: remove cross-version linking restrictions.
      - 4.3: Allow mismatches in interpolation and auxiliary qualification across stages.
	  - 4.4: A stage contains two different blocks, each with no instance name, where the blocks contain a member with the same name.
    Intra-stage linking
      - exactly one main
      - type consistency check of uniforms, globals, ins, and outs, both variables and blocks
      - value checking of global const initializers
      - value checking of uniform initializers
      - location/component/binding/index/offset match check
      - location/component aliasing (except desktop vertex shader inputs)
      - location layout range/overlap semantics
      - geometry shader input array sizes and input layout qualifier declaration
      - compute shader layout(local_size_*) matching
      - mixed es/non-es profiles
      - matching initializers for globals
      - recursion for both functions and subroutines
          - Even the potential for recursion through subroutine uniforms is an error.
      - matching redeclarations of interface blocks
      - read or write to both gl_ClipVertex and gl_ClipDistance
      - write to only one of gl_FragColor, gl_FragData, or user-declared
      - 4.3: Be clear that early_fragment_tests is only needed in one fragment-stage compilation unit.
      - 4.3: Be clear that implicit array sizing is only within a stage, not cross stage.
      - 4.4: overlapping transform/feedback offsets, offset/stride overflow checks, and stride matching
	  - 4.4: If gl_FragCoord is redeclared in any fragment shader in a program, it must be redeclared in all the fragment shaders in that program that have a static use gl_FragCoord
	  - 4.4: An interface contains two different blocks, each with no instance name, where the blocks contain a member with the same name.

Shader Functionality to Implement/Finish
    ESSL 3.0
      - "const" compile-time constant propagation in the front-end has to be complete, for all built-in functions
    GLSL 1.2
      - Handle multiple compilation units per stage
      - Allow initializers on uniform declarations
      - signature matching takes type conversions into account, ambiguity is an error
    GLSL 1.3
      . flat is for both user and predeclared built-in in/out variables
    GLSL 1.3 (Non-ES)
      - Preprocessor token pasting (##), ## does macro expansion after pasting not before
      - non-perspective (linear) interpolation (noperspective)
      - add gl_ClipDistance[] to both vertex and fragment shaders
      - only statically used built-ins have to be redeclared as flat
      - Deprecated gl_ClipVertex
      - deprecate almost all built-in state
      - ftransform() is deprecated
      - Deprecated built-in vertex inputs (attributes) and some outputs (varyings).
    GLSL 1.4 (Non-ES)
      - track as removed in this release, but present in others:
        - Use of gl_ClipVertex.  Use gl_ClipDistance instead.
        - Built-in vertex shader inputs.
        - Built-in uniforms except for depth range parameters
        - Built-in interface between vertex and fragment:  gl_TexCoord, gl_FogFragCoord, and all the color values.
        - Built-in two-sided coloring.
        - Fixed functionality for a programmable stage.  Supply shaders for all stages currently being used.
        - ftransform().  Use invariant outputs instead.
    GLSL 1.5 (Non-ES)
      - Deprecated gl_MaxVaryingComponents
      - Add new minimum maximums for gl_MaxVertexOutputComponents, gl_MaxGeometryInputComponents, gl_MaxGeometryOutputComponents, and gl_MaxFragmentInputComponents, 
                rather than relying on gl_MaxVaryingComponents.  Also, corrected gl_MaxVaryingComponents to be 60 instead of 64.
      - Added gl_PrimitiveID as an input to fragment shaders.
      - Added gl_FragCoord qualifiers origin_upper_left, and pixel_center_integer to modify the values returned by gl_FragCoord (and have no affect on any other aspect of the pipeline or language).
        - including redeclaration of gl_FragCoord that adds nothing
      - Added support for multi-sample textures through sampler2DMS and sampler2DMSArray support in texelFetch() and textureSize().
      - Broadened interface blocks from just uniforms to in and out interfaces as well.
      - Broaden array usage to include vertex shader inputs (vertex in).
      - Added geometry shaders.  This includes targeting layers in FBO rendering.
      - geometry shader layouts: they must be declared, telling the system the primitive input and output types and maximum number of vertices.
      - Added geometry shader constants.
      - Broaden structure usage to include geometry inputs and geometry outputs.
    GLSL 4.0
      - tessellation control stage and tessellation evaluation stage. Includes barrier() built-in for synchronization.
      - Polymorphic functions: Run-time selection of what function gets called, through the new keyword subroutine.
      - 64bit floating point numbers with the new type keyword double.  Built-in functions extended for doubles, and new function matching rules are added to both allow implicit conversions when calling a function and preserve most existing function matching once doubles are included. 
      + More implicit conversions
         + float to double, and similarly for all floating-point vector and matrix types
         + int to uint, and similarly for all integer vector types
         + int to double, and similarly for all vectors of integers and doubles.
         + uint to double, and similarly for all vectors of integers and doubles.
      - Cube map array textures and texture functions texture(), textureSize(), textureLod(), and textureGrad().
      - Sampler arrays can take a variable index now, as long as it's value is uniform for all uses.
      - Per-sample shading. Including sample input mask gl_SampleMaskIn[] and per-sample interpolation, with explicit interpolation built-ins interpolateAtCentroid(), interpolateAtSample(), and interpolateAtOffset().
      - New precise qualifier to disallow optimizations that re-order operations or treat different instances of the same operator with different precision.
      - Add a fused multiply and add built-in, fma(), in relation to the new precise qualifier. (Because <20>a * b + c<> will require two operations under new rules for precise.)
      - Added new built-in floating-point functions 
         - frexp() and ldexp()
         - packUnorm2x16(), packUnorm4x8(),packSnorm4x8(), and packDouble2x32()
         - unpackUnorm2x16(), unpackUnorm4x8(),unpackSnorm4x8(), and unpackDouble2x32()
      - Add new built-in integer functions
         - uaddCarry() andusubBorrow()
         - umulExtended() andimulExtended()
         - bitfieldExtract() andbitfieldInsert()
         - bitfieldReverse()
         - bitCount(),findLSB(), andfindMSB()
      - New built-in to query LOD, textureQueryLod().
      - New overloaded function matching algorithm, handling selection from many valid multiple choices.
      - Texture gather functions that return four texels with a single call.
         - textureGather()
         - textureGatherOffset()
         - textureGatherOffsets()
      - Add streams out from geometry shader. Output can be directed to streams through
         - EmitStreamVertex() and EndStreamPrimitive().
    GLSL 4.1
      - Support for partitioning shaders into multiple programs to provide light-weight mixing of different shader stages.
            (GL_ARB_separate_shader_objects)
        - layout qualifiers
        - redeclaration of input/output blocks
        - ...
      - Add 64-bit floating-point attributes for vertex shader inputs.
      - Support viewport arrays so where the geometry shader selects which viewport array will transform its output.
    GLSL 4.2
      + Move these previously deprecated features to be only in the compatibility profile:
        + The keyword attribute for vertex shader inputs. (Use in instead.)
        + The keyword varying for inputs and outputs. (Use in and out instead.)
        + The original texturing built-in functions. (Use the new forms instead.)
        + The built-in variables gl_FragColor and gl_FragData. (Use out instead.)
        + Built-in constants related to these.
      + Change from ASCII to UTF-8 for the language character set and also allow any characters inside comments (except the byte value 0), 
        including '\'.
      + Add line-continuation using '\', as in C++.
      + ES convergence
        + Clarify that .xyzwxy.xy is illegal, as it temporarily makes a <20>vec6<63>.
        + Clarify that return statements only accept values (no return of a void function).
      - Add image types (GL_ARB_shader_image_load_store)
        + 33 new types, all with <20>image<67> in their name, correspond to the non-shadow texture types
        + addition of memory qualifiers: coherent,volatile, restrict, readonly, and writeonly
        - can read/write/modify images from a shader, through new built-in functions
        - qualifiers can act independently on the opaque shader variable and the backing image, so extra qualifiers can be used to separately qualify these
      + Variables declared in if and else statements are scoped only to the end of those statements, especially for non-compound statements
        Note, this is not backward compatible, it may depend on #version.
      - Allow implicit conversions of return values to the declared type of the function.
      - The const keyword can be used to declare variables within a function body with initializer expressions that are not constant expressions.
      + Qualifiers on variable declarations no longer have to follow a strict order. The layout qualifier can be used multiple times, and multiple parameter qualifiers can be used.
      + Parameter qualifiers can include precision and memory qualifiers.
      - Add a new atomic_uint type to support atomic counters. Also, add built-in functions for manipulating atomic counters.
        - atomicCounterIncrement, atomicCounterDecrement, and atomicCounter
      - Add layout qualifier identifiers binding and offset to bind units to sampler and image variable declarations, atomic counters, and uniform blocks.
      - Add built-in functions to pack/unpack 16 bit floating-point numbers (ARB_shading_language_pack2f).
        - packHalf2x16 and unpackHalf2x16
        - packSnorm2x16and unpackSnorm2x16
      - Add gl_FragDepthlayout qualifiers to communicate what kind of changes will be made to gl_FragDepth(GL_AMD_conservative depth).
      - Add C-style curly brace initializer lists syntax for initializers. Full initialization of aggregates is required when these are used.
      - Allow .length() to be applied to vectors and matrices, returning the number of components or columns.
      + Clarify that .length() returns an int type and can be used as a constant integer expression.
      - Allow swizzle operations on scalars.
      - Positive signed decimal literals, as well as octal and hexadecimal, can set all 32 bits. This includes setting the sign bit to create a negative value.
      - Make GLSL consistent with the API regarding user clipping, by no longer referring to gl_Positionwhen gl_ClipVertex is not written. Rather, user clipping becomes undefined.
      - Clarified that a comma sequence-operator expression cannot be a constant expression. E.g., <20>(2,3)<29> is not allowed, semantically, as a valid constant expression 3, even though it is an expression that will evaluate to 3.
      - Use vec2 instead of vec3 for coordinate in textureGather*(sampler2DRect,...).
      - Clarify that textureGatherOffset() can take non-constants for the offsets.
    GLSL 4.3
      - Add shader storage bufferobjects, as per the ARB_shader_storage_buffer_object extension. 
        This includes 1) allowing the last member of a storage buffer block to be an array that does not 
        know its size until render time, and 2) read/write memory shared with the application and other 
        shader invocations. It also adds the std430layout qualifier for shader storage blocks.
      - Allow .length() on all arrays; returning a compile-time constant or not, depending on how the 
        array is sized, as per the ARB_shader_storage_buffer_object extension.
      - Be clear that implicit array sizing is only within a stage, not cross stage.
      - Array clarifications: 1) All arrays are inherently homogeneous, except for arrays of the new 
        shader storage buffer objects. 2) Arrays of shader storage buffer objects will be dereferenced 
        when the .length() method is used on an unsized array member, so that must a have valid index. 
        3) Arrays of other objects (uniform blocks) containing implicitly sized arrays will have the same 
        implicit size for all elements of the array.
      - Arrays of arrays are now supported, as per the GL_ARB_arrays_of_arraysextension.
      - Compute shaders are now supported, as per the GL_ARB_compute_shader extension.
      - Added imageSize() built-ins to query the dimensions of an image.
      - Define robust out-of-bounds access behavior when enabled, as per the GL_ARB_robust_buffer_access_behavior extension.
      - All choice of depth or stencil texturing, for a packed depth-stencil texture, as per the 
        GL_ARB_stencil_texturing extension.
      - Allow explicit locations/indexes to be assigned to uniform variables and subroutines, as per the 
        GL_ARB_explicit_uniform_location extension.
      - Accept ES GLSL shader #version statements, which will request ES functionality for ES GLSL 
        versions 100 and 300, as per the GL_ARB_ES3_compatibility extension.
      - Clarify and correct scoping rules to what would normally be expected and what was intended. 
        (Function parameters and body nest inside global space. Loop variables and body nest inside 
        loop scope.)
      - There are no digraphs (trigraphs were already disallowed).
      - Remove the CPP difference that it is a compile-time error to use #if or #elif on expressions 
        containing undefined macro names. This reverts back to following expected CPP behavior.
      - Set both gl_MaxFragmentImageUniformsand gl_MaxCombinedImageUniforms to 8.
      - Clarify textureSize() for cube map arrays.
      - For layout qualifiers,
            - make negative output locations a compile-time error, and
            - make indexes outside the range [0,1] a compile-time error.
      - Add textureQueryLevels() built-ins to query the number of mipmap levels, as per the 
        GL_ARB_texture_query_levels extension.
      - Make gl_Layer and gl_ViewportIndex also be inputs to the fragment shader, as per the 
        GL_ARB_fragment_layer_viewport extension.
      - Add more examples and rules to be more specific about the required behavior of the precise 
        qualifier.
      - Clarify fragment output variables cannot be double precision.
      - Allow the new shared keyword to be in layout-qualifier-id, allowing backward compatibility 
        with the shared identifier that was previously used.
      + Added overlooked texture function float textureOffset (sampler2DArrayShadow sampler, vec4 P, vec2 offset [, float bias] ).
      + Add missing type in grammar, ATOMIC_UINT, and missing qualifiers COHERENT, VOLATILE, RESTRICT, READONLY, and WRITEONLY.
      - do version checking for the above
      + Add missing initializer lists to grammar.
    GLSL 4.4
      - Incorporate the ARB_enhanced_layouts extension, which adds
        - compile-time constant expressions for layout qualifier integers
        - new offset and align layout qualifiers for control over buffer block layouts
        - add location layout qualifier for input and output blocks and block members
        - new componentlayout qualifier for finer-grained layout control of input and output variables and blocks
        - new xfb_buffer, xfb_stride, and xfb_offsetlayout qualifiers to allow the shader to control 
          transform feedback buffering.
      + Bug 10530: To be consistent with ES, include sample types as valid in a precision statement. 
        Note the defaults are irrelevant, as precision qualifiers are not required or have any meaning.