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 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); must be SAMPLE_POSITION. corresponds to the sample for which the location should be set. The sample location is set by passing two floating point values in and , each between 0.0 and 1.0, inclusive, corresponding to the and 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 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 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 is NULL, 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 . 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.