[platform/upstream/glslang.git] / Todo.txt

Current functionality level: ESSL 3.0, GLSL 1.5

Bugs
 - implicitly-sized gl_ClipDistance[] (at least in tessellation shaders) with sizes greater than one are not getting sizes greater than one

+ create version system

Link Validation
    + provide input config file for setting limits
      - also consider spitting out measures of complexity
    + ensure no static references thrown away
    - generate static use of object even if the only use is to access the length of its array
    Cross-stage linking
      - type consistency check of uniform and ins <-> outs, both variables and blocks, stage-specific arrayness matching
      - location/binding/index check
      - mixed es/non-es profiles
      - statically consumed input not produced by previous stage
      - give error for sharing a packed block
      - 1.2: matching initializers for uniforms
      - 1.3: only statically used built-ins have to be redeclared as flat
      - 1.5: matching between gl_PerVertex blocks and gl_PerFragment blocks
      - 1.3: deprecated mixing fixed vertex/fragment stage with programmable fragment/vertex stage.
      + 4.0: tessellation primitive, vertices, spacing, order, 
      - 4.3: compute shader not combined with any other stages
      - 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, single shader
      + recursion for functions
      - limits checking:
          + bindings
          - number of input/output compononents
          + tessellation limits
          + tessellation primitive array sizing consistency
          + Non ES: gl_TexCoord can only have a max array size of up to gl_MaxTextureCoords
          + Non ES: gl_ClipDistance ...
          - ...
      + exactly one main
      + ES 3.0: fragment outputs all have locations, if more than one
      + location aliasing/overlap (except desktop vertex shader inputs)
      - Non ES: binding overlap for atomic counters
      + Non ES: geometry shader input array sizes and input layout qualifier declaration
      + Non ES: read or write to both gl_ClipVertex and gl_ClipDistance
      + Non ES: write to only one of gl_FragColor, gl_FragData, or user-declared
      + 1.50: match between all explicit input array sizes and input primitive
      + 1.50: at least one geometry shader says input primitive and at least one says output primitive...
      + 1.50: at least one geometry shader says max_vertices...
      + 1.50: origin_upper_left and pixel_center_integer have to match
      - Even the potential for recursion through subroutine uniforms is an error.
      - 4.4: An interface contains two different blocks, each with no instance name, where the blocks contain a member with the same name.
      - 4.4: component aliasing (except desktop vertex shader inputs)
      - 4.4: overlapping transform/feedback offsets, offset/stride overflow checks, and stride matching
    Intra-stage linking, multiple shader (Non-ES)
      + type consistency check of uniforms, globals, ins, and outs
      + value checking of global const initializers
      + value checking of uniform initializers
      + location match
      - block matching
      - component/binding/index/offset match check
      + compute shader layout(local_size_*) matching
      + mixed es/non-es profiles are an error
      - matching redeclarations of interface blocks
      - 4.3: implicit array sizing is cross shader within a stage
      - 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

Shader Functionality to Implement/Finish
    ESSL 2.0 (#version 100)
      + implement non-inductive loop limitation detection
      + implement non-inductive array accesses limitation detection
    ESSL 3.0
      - "const" compile-time constant propagation in the front-end has to be complete, for all built-in functions
    ESSL 3.1
      + Compute shaders
      + Shader storage buffer objects
      - Arrays of arrays
      + Atomic counters
      + Images
      + Separate program objects (also known as separate shader objects)
      + Explicit uniform locations
      + Texture gather
      + Bitfield operations
      + Integer mix function
    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 redeclaration of built-in variables
      - Preprocessor token pasting (##), ## does macro expansion after pasting not before
      + non-perspective (linear) interpolation (noperspective)
      + add gl_ClipDistance[] to both vertex and fragment shaders
      + 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)
      + rectangular textures
      + 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. 
        + 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.
      + texel offset limit checking
      + 1.50: geometry shaders: max_vertices must be checked against gl_MaxGeometryOutputVertices (maybe at compile time)
    GLSL 3.3
      + Add ARB_explicit_attrib_location extension
      + Add ARB_shader_bit_encoding extension
    GLSL 4.0
      + tessellation control stage and tessellation evaluation stage. Includes barrier() built-in for synchronization.
        + patch in, patch out
        + input/output arrays
          + unsized array sizing to gl_MaxPatchVertices, including gl_in/gl_out
        + built-in variables, functions, and constants verification
        + layout qualifiers for primitive types
      - 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 \93a * b + c\94 will require two operations under new rules for precise.)
      - Added new built-in floating-point functions 
         - frexp() and ldexp()
         + packUnorm2x16(), unpackUnorm2x16(),
         - packUnorm4x8(),packSnorm4x8(), and packDouble2x32()
         - 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 \93vec6\94.
        + 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 \93image\94 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
        + early_fragment_tests
      + 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_FragDepth layout 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.
      + Clarified that a comma sequence-operator expression cannot be a constant expression. E.g., \93(2,3)\94 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 buffer objects, as per the ARB_shader_storage_buffer_object extension. This includes 
            + allowing the last member of a storage buffer block to be an array that does not know its size until render time
            + read/write memory shared with the application and other shader invocations
            + adding the std430 layout qualifier for shader storage blocks
            + add atomic built-ins
            + layout(binding=)
      - 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: 
            - All arrays are inherently homogeneous, except for arrays of the new shader storage buffer objects
            - 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. 
            - 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_arrays extension.
      + Compute shaders are now supported, as per the GL_ARB_compute_shader extension.
      - Added imageSize() built-ins to query the dimensions of an image.
      - 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_MaxFragmentImageUniforms and gl_MaxCombinedImageUniforms to 8.
      - Clarify textureSize() for cube map arrays.
      - For layout qualifiers,
            + make negative output locations a compile-time error, once integer expressions are allowed in layouts
            - 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.
      - 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.
      + 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 component layout 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.
    GLSL 4.5
      + Incorporate the ARB_ES3_1_compatibility extension
        + Supports OpenGL ES 310 shaders.
        + Adds imageAtomicExchange() built-in function for floating-point images.
        + Adds coherent to atomic and image-atomic built-in function parameters.
        + Adds gl_HelperInvocation built-in variable to say whether a fragment shader invocation is 
              only as a helper, so the shader can skip code not needed or harmful when in a helper invocation.
        + Adds gl_MaxSamplesbuilt-in constant, and several other built-in constants.
        + Adds mix() built-in functions for selection of int, uint, andbool components.
      + Incorporate the GL_ARB_shader_texture_image_samples extension to query how many samples are in a multi-sample texture or image.
      + Incorporate the GL_ARB_cull_distance extensions to add the built-in variable gl_CullDistance[] , which will cull whole primitives.
      + Incorporate the GL_ARB_derivative_control extension