blob: 149c50c5bd5dc12437837c016436794cda84eea9 [file] [log] [blame]
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.