readme.txt

A simple fragment program that converts every pixel to greyscale.

This is the spec for ARB fp1.0

Name

    ARB_fragment_program

Name Strings

    GL_ARB_fragment_program

Contributors

    Bob Beretta
    Pat Brown
    Matt Craighead
    Cass Everitt
    Evan Hart
    Jon Leech
    Bill Licea-Kane
    Bimal Poddar
    Jeremy Sandmel
    Jon Paul Schelter
    Avinash Seetharamaiah
    Nick Triantos

    and contributors to the ARB_vertex_program working group,
    the product of which provided the basis for this spec

Contact

    Benj Lipchak, ATI Research (blipchak 'at' ati.com)

IP Status

    Microsoft claims to own intellectual property related to this 
    extension.

Status

    Complete.  Approved by ARB on September 18, 2002

Version

    Last Modified Date: August 22, 2003
    Revision: 26

Number

    ARB Extension #27

Dependencies

    The extension is written against the OpenGL 1.3 Specification.

    OpenGL 1.3 is required.

    EXT_texture_lod_bias or OpenGL 1.4 is required.

    OpenGL 1.4 affects the definition of this extension.

    ARB_vertex_blend and EXT_vertex_weighting affect the definition of 
    this extension.

    ARB_matrix_palette affects the definition of this extension.

    ARB_transpose_matrix affects the definition of this extension.

    EXT_fog_coord affects the definition of this extension.

    EXT_texture_rectangle affects the definition of this extension.

    ARB_shadow interacts with this extension.

    ARB_vertex_program interacts with this extension.

    ATI_fragment_shader interacts with this extension.

    NV_fragment_program interacts with this extension.


Overview

    Unextended OpenGL mandates a certain set of configurable per-
    fragment computations defining texture application, texture 
    environment, color sum, and fog operations.  Several extensions have 
    added further per-fragment computations to OpenGL.  For example, 
    extensions have defined new texture environment capabilities 
    (ARB_texture_env_add, ARB_texture_env_combine, ARB_texture_env_dot3,
    ARB_texture_env_crossbar), per-fragment depth comparisons 
    (ARB_depth_texture, ARB_shadow, ARB_shadow_ambient, 
    EXT_shadow_funcs), per-fragment lighting (EXT_fragment_lighting, 
    EXT_light_texture), and environment mapped bump mapping 
    (ATI_envmap_bumpmap).  

    Each such extension adds a small set of relatively inflexible per-
    fragment computations.

    This inflexibility is in contrast to the typical flexibility 
    provided by the underlying programmable floating point engines 
    (whether micro-coded fragment engines, DSPs, or CPUs) that are 
    traditionally used to implement OpenGL's texturing computations.  
    The purpose of this extension is to expose to the OpenGL application 
    writer a significant degree of per-fragment programmability for 
    computing fragment parameters.

    For the purposes of discussing this extension, a fragment program is 
    a sequence of floating-point 4-component vector operations that 
    determines how a set of program parameters (not specific to an
    individual fragment) and an input set of per-fragment parameters are 
    transformed to a set of per-fragment result parameters.

    The per-fragment computations for standard OpenGL given a particular 
    set of texture and fog application modes (along with any state for 
    extensions defining per-fragment computations) is, in essence, a 
    fragment program.  However, the sequence of operations is defined 
    implicitly by the current OpenGL state settings rather than defined 
    explicitly as a sequence of instructions.

    This extension provides an explicit mechanism for defining fragment 
    program instruction sequences for application-defined fragment 
    programs.  In order to define such fragment programs, this extension 
    defines a fragment programming model including a floating-point
    4-component vector instruction set and a relatively large set of 
    floating-point 4-component registers.

    The extension's fragment programming model is designed for efficient
    hardware implementation and to support a wide variety of fragment 
    programs.  By design, the entire set of existing fragment programs 
    defined by existing OpenGL per-fragment computation extensions can 
    be implemented using the extension's fragment programming model.

Issues

    This extension is closely related to ARB_vertex_program, and is in 
    sync with revision 36 of that spec.  ARB_fragment_program will 
    continue to track changes made to ARB_vertex_program.

    (1) Should we provide precision queries?

      RESOLVED: We've decided not to include precision queries.
      Implementations are expected to meet or exceed the precision 
      guidelines set forth in the core GL spec, section 2.1.1, p. 6,
      as ammended by this extension.

      To summarize section 2.1.1, the maximum representable magnitude of 
      colors must be at least 2^10, while the maximum representable 
      magnitude of other floating-point values must be at least 2^32.  
      The individual results of floating-point operations must be 
      accurate to about 1 part in 10^5.

      Here are the reasons why precision queries were not included:
        1. It is unclear what the queries should be:
           a) min, max, [0,1) granularity
           b) min +, max +, min -, max -, [0,1) granularity
           c) IEEE mantissa bits, IEEE exponent bits
        2. Due to instruction emulation, there is no way to query the 
           actual precision that can be expected.  Should the query 
           return the best-case or worst-case precision?
        3. Implementations may support multiple precisions, on a per-
           instruction basis or across the board.  How would this be 
           exposed?
        4. Current implementations are able to meet the minimum 
           requirements specified in the core GL, thanks to its
           sufficiently loose wording "... so that the individual 
           results of floating-point operations are accurate to ABOUT 
           1 part in 10^5."  (Emphasis added.)
        5. A conformance test can act as watchdog to ensure 
           implementations are not cutting corners on precision.
        6. Adding precision queries would require a new entrypoint.

      See issue 22 regarding reduced-precision modes.

    (2) Should the LOD biased texture sample be optional?

      RESOLVED: TXB support is mandatory.  This exposes useful 
      functionality which enables blurring and sharpening effects.  It 
      will be more useful to entirely override derivatives (scale 
      factor) rather than just biasing the level-of-detail.  This would 
      be a future extension to fragment programs.

      It should be noted here that the bias introduced per-fragment by 
      TXB is added to any per-object or per-stage LOD bias.  If per-
      fragment LOD bias is not necessary, using the per-object and/or 
      per-stage LOD biases may perform better.

    (3) Should we include the ability to bind to the color matrix?  How
    about others?  Program matrices?

      RESOLVED: We will not specifically add anything that depends on 
      the ARB_imaging subset.  So we have not included matrix bindings 
      to the color matrix (or parameter bindings to the color biases, 
      etc.).  However, we have included matrix binding support and 
      support for all of the matrices present in ARB_vertex_program.

    (4) Should we include the ability to bind to just a texcoord 
    attribute's S,T components?  (Or just S, or S,T,P for that matter?) 

      RESOLVED: No.  Issue #15 below obviates this issue by making the
      texture coordinate usage within a program explicit, thereby making 
      optimizations to reduce the number of interpolated texture 
      coordinates something an implementation can do at compile time 
      instead of having to do it during every texture target change.

    (5) What other instructions should be added?  Should any be removed?

      RESOLVED: The differences between the ARB_vertex_program 
      instruction set and the ARB_fragment_program instruction set are
      minimal.  ARB_fragment_program removes the LOG and EXP rough
      approximation instructions and the ARL address register load
      instruction.  ARB_fragment_program adds the SIN/COS/SCS 
      trigonometric instructions, the LRP linear interpolation 
      instruction, the CMP compare instruction, and the TEX/TXP/TXB/KIL
      texture instructions.

    (6) Should depth output be a program option or a mandatory feature?
 
      RESOLVED: Depth output capability should be mandatory.

    (6a) How should per-vertex geometric depth clipping be handled when 
      replacing depth in a fragment program?

      RESOLVED: Per-vertex geometric depth clipping should be performed 
      by the GL as usual, so no spec change is required.  The ideal
      behavior would be to disable near and far clipping planes when
      replacing depth, but not all implementations can natively support
      disabling individual clip planes.

    (6b) How should depth output from the fragment program be further 
    processed before being handed to the per-fragment operations?

      RESOLVED: Depth gets clamped by GL to [0,1].  App has access to 
      depth range as a bindable parameter if it wants to either scale 
      and bias its depth to fall within the depth range, or to kill 
      fragments outside the depth range.

    (7) If a fragment program does not write a color value, what should
    be the final color of the fragment?

      RESOLVED: The final fragment color is undefined.  Note that it may
      be perfectly reasonable to have a program that computes depth 
      values but not colors.  Fragment colors are often irrelevant if
      color writes are disabled (via ColorMask).

    (7a) If a fragment program does not write a depth value, what should 
    be the final depth value of the fragment?

      RESOLVED: "Depth fly-over" (using the conventional depth produced
      by rasterization) should happen whenever a depth-replacing program 
      is not in use.  A depth-replacing program is defined as a program
      that writes to result.depth in at least one instruction.  The
      presence of a depth declaration alone DOES NOT designate a depth-
      replacing program.  The intention is that a future extension
      introducing conditional execution will still consider a program to
      be depth-replacing even if the instruction(s) writing to 
      result.depth do(es) not execute.

      Other considered definitions of depth-replacing program:
        1. The presence of a depth declaration -OR- the use of 
           result.depth as an instruction destination anywhere in the 
           program designates a depth-replacing program.
        2. Every program is a depth-replacing program, but the GL 
           initializes the depth output to be the depth produced by 
           rasterization.  The app may then overwrite the depth output.
        3. Every program is a depth-replacing program, and the app is 
           solely responsible for copying the depth input to depth 
           output if desired.

    (8) Should relative addressing, like that defined in 
    ARB_vertex_program, be supported in this spec?