Name

    AMD_sample_positions

Name Strings

    GL_AMD_sample_positions

Contact

    Mais Alnasser, AMD (mais.alnasser 'at' amd.com)

Contributors

    Mais Alnasser, AMD
    Graham Sellers, AMD
    Nick Haemel, AMD

Status

    Complete, shipping.

Version

    Last Modified Date:         04/06/11
    Revision:                   7

Number

    405

Dependencies

    OpenGL 1.1 is required.

    EXT_framebuffer_multisample or OpenGL 3.2 is required.

    This extension interacts with the ARB_texture_multisample extension.

    This extension is written against the OpenGL 3.2 (Core) specification.

Overview

    This extension provides a mechanism to explicitly set sample positions for a
    FBO with multi-sampled attachments. The FBO will use identical sample locations
    for all pixels in each attachment. This forces TEXTURE_FIXED_SAMPLE_LOCATIONS
    to TRUE if a multi-sampled texture is specified using TexImage2DMultisample
    or TexImage3DMultisample. That is, using GetTexLevelParameter to query
    TEXTURE_FIXED_SAMPLE_LOCATIONS will always return TRUE if the mechanism is
    explicitly used to set the sample positions.

New Tokens

    Accepted by the <pname> parameter of GetFloatv:

        SUBSAMPLE_DISTANCE_AMD                          0x883F

New Procedures and Functions

    void SetMultisamplefvAMD(enum pname, uint index, const float *val);

Modifications to Chapter 2 of the OpenGL 3.2 (Core) Specification (OpenGL
    Operation)

    None.

Modifications to Chapter 3 of the OpenGL 3.2 Specification (Rasterization)

    None.

Additions to Chapter 4 of the OpenGL 3.2 (Core) Specification
(Per-Fragment Operations and the Frame Buffer)

    Modify Section 4.1.3, Multisample Fragment Operations

    Modify the discussion of SampleMaski to start with "Next" instead
    of "Finally".

    Add after the discussion of SampleMaski:

    Finally, a single sample location can be modified for all pixels in
    a multi-sampled framebuffer using the following call:

        void SetMultisamplefvAMD(enum pname, uint index, clampf *val);

    <pname> must be SAMPLE_POSITION. <index> corresponds to the
    sample for which the location should be set. The sample location
    is set by passing two floating point values in <val[0]> and
    <val[1]>, each between 0.0 and 1.0, inclusive, corresponding to the <x>
    and <y> locations in pixel space of that sample, respectively . (0.5, 0.5)
    thus corresponds to the pixel center. The error INVALID_VALUE is generated
    if <index> is greater than or equal to the value of SAMPLES.

    SetMultisamplefvAMD generates an INVALID_OPERATION error if the currently 
    bound framebuffer is incomplete or is the default framebuffer.

    Using SetMultisamplefvAMD will cause any multisampled texture attached
    to the currently bound FBO to use identical sample locations for all
    of its pixels forcing <fixedsamplelocations> to TRUE. That is, using
    GetTexLevelParameter to query TEXTURE_FIXED_SAMPLE_LOCATIONS will
    always return TRUE if the new mechanism is used to explicitly set
    the sample positions.

    If <val> is NULL, <index> is ignored and all sample positions are returned
    to their default values.

    The subpixel range [0,1] is discretized based on the implementation-
    dependent value of SUBSAMPLE_DISTANCE_AMD. GetFloatv can be used with
    SUBSAMPLE_DISTANCE_AMD as the pname parameter to query the subpixel
    precision, which is the same for both the vertical and horizontal
    directions. Given two sample positions (x0, y0) and (x1, y1), one can make
    sure they don't fall in the same subpixel if

            abs(x0-x1) >= ssd and abs(y0-y1) >= ssd,

    where ssd is the float value returned when querying SUBSAMPLE_DISTANCE_AMD.

    The quantized sample positions may be queried by calling GetMultisamplefv.

Additions to Chapter 5 of the OpenGL 3.2 (Core) Specification (Special Functions)

    None.

Additions to Chapter 6 of the OpenGL 3.2 (Core) Specification (State and
State Requests)

    None.

GLX Protocol

    None.

Errors

    The error INVALID_VALUE is generated by SetMultisamplefvAMD if index 
    is greater than or equal to the value of SAMPLES.

    The error INVALID_OPERATION is generated by SetMultisamplefvAMD if 
    the currently bound framebuffer is the default framebuffer.
    
    The error INVALID_OPERATION is generated by SetMultisamplefvAMD if 
    the currently bound framebuffer is incomplete.

New State

    None.

New Implementation Dependent State

    Add to Table 6.12, Multisampling, p.277:

    Get Value                    Type    Get Command  Value   Description                   Sec.
    ---------                    ------- -----------  ------- ------------------------      ------
    SUBSAMPLE_DISTANCE_AMD       R+      GetFloatv    -       precision step between        4.1.3
                                                              subsamples

Interaction with ARB_texture_multisample

    If ARB_texture_multisample is not supported, remove all references to
    TEXTURE_FIXED_SAMPLE_LOCATIONS and to <fixedsamplelocations>. Also, should
    ARB_texture_multisample not be supported, the GetMultisamplefv entry point
    must be added as described in the specification of ARB_texture_multisample
    for the sake of completeness.

Issues

    (1) What happens if an app just sets one sample position,
        index 3 for example? 

    RESOLVED: Any attachment to the bound FBO will have the index 3
    position updated. All the rest of the positions will keep their
    original values. Any other fbos will not be affected by this change.

    (2) How does an app get back to the default state after setting 
        sample positions? 

    RESOLVED: SetMultisamplefvAMD(SAMPLE_POSITION, 0, NULL) will restore
    all the sample positions to their default state.

    (3) Should we also expose the precision? An app can use it in setting 
        sample positions?

    RESOLVED: SUBSAMPLE_DISTANCE_AMD is added as a new token. It can be used 
    by GetFloatv to query the precision step, which will be the same for 
    both the vertical and horizontal directions. The subpixel range [0,1] 
    is discretized based on the value of SUBSAMPLE_DISTANCE_AMD. Let ssd be the
    float value returned when SUBSAMPLE_DISTANCE_AMD is queried, then one can 
    infer the subpixilization to be 1/ssd+1. For example, if ssd = 0.06667
    then the pixel is subdivided into 1/0.0667+1=16 subpixels in each 
    dimension. 

    One can also avoid using sample positions that would map to the same
    subpixel. A coordinate c will map to the greatest multiple of ssd that 
    is less or equal to c. For example, given two sample positions, (x0, y0) 
    and (x1, y1), if abs(x1-x0) < ssd and abs(y1-y0) < ssd, then both points 
    will map to the same subpixel, which means the application might want to  
    substitute one of these positions with another that is not redundant. 
    Using numerical values as an example, let a=(0.201, 0.0) and b=(0.25, 0.5) 
    be sample positions and ssd = 0.06667. Both the x-coordinate values 0.201 
    and 0.25 fall between 0.06667*3=0.2 and 0.06667*4=0.26667 and would  
    therefore map to the same value of 0.2. The y-coordinates also map to the 
    same value of 0 because they both belong in the range [0, 0.06667). This 
    means the two points are redundant. Therefore, the application should 
    choose a different point c=(0.3, 0.45) for example. c would be a good 
    choice because the distance between its x-coordinate and a's x-coordinate 
    is greater than ssd, that is 0.3-0.201 > 0.06667.

    (4) Aside from evaluating the above equations, how can an application tell
        what subsample positions the hardware is using?

    RESOLVED: GetMultisamplefv will return the quantized sample positions,
    not the original positions sent to SetMultisamplefvAMD.

Revision History

    Rev.    Date    Author    Changes
    ----  --------  --------  -----------------------------------------
    7     4/06/11   gsellers  Clean up for posting on public registry.
    6     6/30/10   gsellers  Assign enumerant value for SUBSAMPLE_DISTANCE_AMD.
    5     3/18/10   malnasse  Generate INVALID_OPERATION error if attempting
                              to set sample positions for an incomplete framebuffer
    4     2/23/10   malnasse  Generate INVALID_OPERATION error if attempting
                              to set sample positions for the default framebuffer
    3     2/05/10   gsellers  Minor cleanup. Submission to AMD repository.
    2     2/02/10   malnasse  - Added a mechanism to restore the sample
                                positions to their default state.
                              - Added the issues section.
                              - Added new token to help query the subsample precision
    1     1/27/10   malnasse  First revision.