readme.txt

A simple fragment program that converts every pixel to greyscale.

             if (i.input3 && i.input3.type == TEMP)
               aluTemps |= (1 << i.input3.index);
             if (i.output.type == TEMP)
               aluTemps |= (1 << i.output.index);
           }
           if ((i.op != KILL) && (i.output.type == TEMP))
             tempsOutput |= (1 << i.output.index);
         }

       For example, the following programs would have 1, 2, and 3
       texture indirections, respectively:

         !!ARBfp1.0
         # No texture instructions, but always 1 indirection
         MOV result.color, fragment.color;
         END

         !!ARBfp1.0
         # A simple dependent texture instruction, 2 indirections
         TEMP myColor;
         MUL myColor, fragment.texcoord[0], fragment.texcoord[1];
         TEX result.color, myColor, texture[0], 2D;
         END

         !!ARBfp1.0
         # A more complex example with 3 indirections
         TEMP myColor1, myColor2;
         TEX myColor1, fragment.texcoord[0], texture[0], 2D;
         MUL myColor1, myColor1, myColor1;
         TEX myColor2, fragment.texcoord[1], texture[1], 2D;
         # so far we still only have 1 indirection
         TEX myColor2, myColor1, texture[2], 2D;      # This is #2
         TEX result.color, myColor2, texture[3], 2D;  # And #3
         END

       Note that writemasks for the temporaries written and swizzles 
       for the temporaries read are not taken into consideration when
       counting indirections.  This makes hand-counting of indirections
       by a developer an easier task.

       Native texture indirections may be counted differently by an
       implementation to reflect its exact restrictions, to reflect the 
       true dependencies taking into account writemasks and swizzles, 
       and to reflect optimizations such as instruction reordering.  

       For implementations with no restrictions on the number of
       indirections, the maximum indirection count will equal the
       maximum texture instruction count.

    (25) How can a program reduce SCS's scalar operand to the 
    fundamental period [-PI,PI]?

       RESOLVED: Unlike the individual SIN and COS instructions, SCS 
       requires that its argument be reduced ahead of time to the 
       fundamental period.  The reason SCS doesn't perform this 
       operation automatically is that it may make unnecessary redundant 
       work for programs that already have their operand in the correct 
       range.  Other programs that do need to reduce their operand 
       simply need to add a block of code before the SCS instruction:

         PARAM myParams = { 0.5, -3.14159, 6.28319, 0.15915 };
         MAD myOperand.x, myOperand.x, myParams.w, myParams.x; # a = (a/(2*PI))+0.5
         FRC myOperand.x, myOperand.x;                         # a = frac(a)
         MAD myOperand.x, myOperand.x, myParams.z, myParams.y  # a = (a*2*PI)-PI
         ...
         SCS myResult, myOperand.x;

    (26) Is depth output from a fragment program guaranteed to be
    invariant with respect to depth produced via conventional 
    rasterization?

      RESOLVED:  No.  The floating-point representation of depth values 
      output from a fragment program may lead to the output of depth 
      with less precision than the depth output by convention GL 
      rasterization.  For example, a floating-point representation with 
      16 bits of mantissa will certainly produce depth with lesser 
      precision than that of conventional rasterization used in 
      conjunction with a 24-bit depth buffer, where all values are
      maintained as integers.  Be aware of this when mixing conventional 
      GL rendering with fragment program rendering.

    (27) How can conventional GL fog application be achieved within a 
    fragment program?

      RESOLVED: Program options have been introduced that allow a 
      program to request fog to be applied to the final clamped fragment 
      color before being passed along to the antialiasing application 
      stage.  This makes it easy for:
        1. developers to request conventional fog behavior
        2. implementations with dedicated fog hardware to use it
        3. implementations without dedicated fog hardware, so they need 
           not track fog state after compilation, and constantly 
           recompile when fog state changes.

      The three mandatory options are ARB_fog_exp, ARB_fog_exp2, and 
      ARB_fog_linear.  As these options are mutually exclusive by
      nature, specifying more than one is not useful.  If more than one
      is specified, the last one encountered in the <optionSequence> 
      will be the one to actually modify the execution environment.

    (28) Why have all of the enums, entrypoints, GLX protocol, and spec 
    language shared with ARB_vertex_program been reproduced here?

      RESOLVED: The two extensions are independent of one another, in
      so far as an implementation need not support both of them in order 
      to support one of them.  Everything needed to implement or make 
      use of ARB_fragment_program is present in this spec without the
      need to refer to the ARB_vertex_program spec.  When and if these
      two extensions are incorporated into the core OpenGL, the
      significant overlap of the two will be collapsed into a single
      instance of the shared parts.

    (29) How might an implementation implement the fog options?  To What
    does the extra resource consumption described in 3.11.4.5.1 
    correspond?

      RESOLVED: The following code snippets reflect possible
      implementations of the fog options.  While an implementation may
      use other instruction sequences to achieve the same result, or may 
      use external fog hardware if available, all implementations must 
      enforce the API-level resource consumption as described: 2 params,
      1 temp, 1 attribute, and 3, 4, or 2 instructions.  "finalColor" in
      the examples below is the color that would otherwise be 
      "result.color", with components clamped to the range [0,1].
      "result.color.a" is assumed to have already been written, as fog
      blending does not affect the alpha component.

      EXP:
        # Exponential fog
        # f = exp(-d*z)
        #
        PARAM p = {DENSITY/LN(2), NOT USED, NOT USED, NOT USED};
        PARAM fogColor = state.fog.color;
        TEMP fogFactor;
        ATTRIB fogCoord = fragment.fogcoord.x;
        MUL fogFactor.x, p.x, fogCoord.x;
        EX2_SAT fogFactor.x, -fogFactor.x;
        LRP result.color.rgb, fogFactor.x, finalColor, fogColor;

      EXP2:
        #
        # 2nd-order Exponential fog
        # f = exp(-(d*z)^2)
        #
        PARAM p = {DENSITY/SQRT(LN(2)), NOT USED, NOT USED, NOT USED};
        PARAM fogColor = state.fog.color;
        TEMP fogFactor;
        ATTRIB fogCoord = fragment.fogcoord.x;
        MUL fogFactor.x, p.x, fogCoord.x;
        MUL fogFactor.x, fogFactor.x, fogFactor.x;
        EX2_SAT fogFactor.x, -fogFactor.x;
        LRP result.color.rgb, fogFactor.x, finalColor, fogColor;

      LINEAR:
        #
        # Linear fog
        # f = (end-z)/(end-start)
        #
        PARAM p = {-1/(END-START), END/(END-START), NOT USED, NOT USED};
        PARAM fogColor = state.fog.color;
        TEMP fogFactor;
        ATTRIB fogCoord = fragment.fogcoord.x;
        MAD_SAT fogFactor.x, p.x, fogCoord.x, p.y;
        LRP result.color.rgb, fogFactor.x, finalColor, fogColor;

    (30) Why is the order of operands for the CMP instruction different
    than the order used by another popular graphics API?

      RESOLVED: No other graphics API was used as a basis for the
      design of ARB_fragment_program except ARB_vertex_program, which
      did not have a CMP instruction.  This independent evolution
      naturally led to differences in minor details such as order of
      operands.  This discrepancy is noted here to help developers 
      familiar with the other API to avoid this potential pitfall.

    (31) Is depth offset applied to the window z value before it enters
    the fragment program?

      RESOLVED: As in the base OpenGL specification, the depth offset
      generated by polygon offset is added during polygon rasterization.
      The depth value provided to shaders in the fragment.position.z
      attribute already includes polygon offset, if enabled.  If the
      depth value is replaced by a fragment program, the polygon offset
      value will NOT be recomputed and added back after fragment program
      execution.

      NOTE: This is probably not desirable for fragment programs that
      modify depth values since the partials used to generate the offset
      may not match the partials of the computed depth value.


New Procedures and Functions

    void ProgramStringARB(enum target, enum format, sizei len, 
                          const void *string); 

    void BindProgramARB(enum target, uint program);

    void DeleteProgramsARB(sizei n, const uint *programs);

    void GenProgramsARB(sizei n, uint *programs);

    void ProgramEnvParameter4dARB(enum target, uint index,
                                  double x, double y, double z, double w);
    void ProgramEnvParameter4dvARB(enum target, uint index,
                                   const double *params);
    void ProgramEnvParameter4fARB(enum target, uint index,
                                  float x, float y, float z, float w);
    void ProgramEnvParameter4fvARB(enum target, uint index,
                                   const float *params);

    void ProgramLocalParameter4dARB(enum target, uint index,
                                    double x, double y, double z, double w);
    void ProgramLocalParameter4dvARB(enum target, uint index,
                                     const double *params);
    void ProgramLocalParameter4fARB(enum target, uint index,
                                    float x, float y, float z, float w);
    void ProgramLocalParameter4fvARB(enum target, uint index,
                                     const float *params);

    void GetProgramEnvParameterdvARB(enum target, uint index,
                                     double *params);
    void GetProgramEnvParameterfvARB(enum target, uint index, 
                                     float *params);

    void GetProgramLocalParameterdvARB(enum target, uint index,
                                       double *params);
    void GetProgramLocalParameterfvARB(enum target, uint index, 
                                       float *params);

    void GetProgramivARB(enum target, enum pname, int *params);

    void GetProgramStringARB(enum target, enum pname, void *string);

    boolean IsProgramARB(uint program);


New Tokens

    Accepted by the <cap> parameter of Disable, Enable, and IsEnabled, 
    by the <pname> parameter of GetBooleanv, GetIntegerv, GetFloatv, 
    and GetDoublev, and by the <target> parameter of ProgramStringARB,
    BindProgramARB, ProgramEnvParameter4[df][v]ARB,
    ProgramLocalParameter4[df][v]ARB, GetProgramEnvParameter[df]vARB, 
    GetProgramLocalParameter[df]vARB, GetProgramivARB and
    GetProgramStringARB.

        FRAGMENT_PROGRAM_ARB                            0x8804

    Accepted by the <format> parameter of ProgramStringARB:

        PROGRAM_FORMAT_ASCII_ARB                        0x8875

    Accepted by the <pname> parameter of GetProgramivARB:

        PROGRAM_LENGTH_ARB                              0x8627
        PROGRAM_FORMAT_ARB                              0x8876
        PROGRAM_BINDING_ARB                             0x8677
        PROGRAM_INSTRUCTIONS_ARB                        0x88A0
        MAX_PROGRAM_INSTRUCTIONS_ARB                    0x88A1
        PROGRAM_NATIVE_INSTRUCTIONS_ARB                 0x88A2
        MAX_PROGRAM_NATIVE_INSTRUCTIONS_ARB             0x88A3
        PROGRAM_TEMPORARIES_ARB                         0x88A4
        MAX_PROGRAM_TEMPORARIES_ARB                     0x88A5
        PROGRAM_NATIVE_TEMPORARIES_ARB                  0x88A6
        MAX_PROGRAM_NATIVE_TEMPORARIES_ARB              0x88A7
        PROGRAM_PARAMETERS_ARB                          0x88A8
        MAX_PROGRAM_PARAMETERS_ARB                      0x88A9
        PROGRAM_NATIVE_PARAMETERS_ARB                   0x88AA
        MAX_PROGRAM_NATIVE_PARAMETERS_ARB               0x88AB