1Name 2 3 AMD_sample_positions 4 5Name Strings 6 7 GL_AMD_sample_positions 8 9Contact 10 11 Mais Alnasser, AMD (mais.alnasser 'at' amd.com) 12 13Contributors 14 15 Mais Alnasser, AMD 16 Graham Sellers, AMD 17 Nick Haemel, AMD 18 19Status 20 21 Complete, shipping. 22 23Version 24 25 Last Modified Date: 04/06/11 26 Revision: 7 27 28Number 29 30 405 31 32Dependencies 33 34 OpenGL 1.1 is required. 35 36 EXT_framebuffer_multisample or OpenGL 3.2 is required. 37 38 This extension interacts with the ARB_texture_multisample extension. 39 40 This extension is written against the OpenGL 3.2 (Core) specification. 41 42Overview 43 44 This extension provides a mechanism to explicitly set sample positions for a 45 FBO with multi-sampled attachments. The FBO will use identical sample locations 46 for all pixels in each attachment. This forces TEXTURE_FIXED_SAMPLE_LOCATIONS 47 to TRUE if a multi-sampled texture is specified using TexImage2DMultisample 48 or TexImage3DMultisample. That is, using GetTexLevelParameter to query 49 TEXTURE_FIXED_SAMPLE_LOCATIONS will always return TRUE if the mechanism is 50 explicitly used to set the sample positions. 51 52New Tokens 53 54 Accepted by the <pname> parameter of GetFloatv: 55 56 SUBSAMPLE_DISTANCE_AMD 0x883F 57 58New Procedures and Functions 59 60 void SetMultisamplefvAMD(enum pname, uint index, const float *val); 61 62Modifications to Chapter 2 of the OpenGL 3.2 (Core) Specification (OpenGL 63 Operation) 64 65 None. 66 67Modifications to Chapter 3 of the OpenGL 3.2 Specification (Rasterization) 68 69 None. 70 71Additions to Chapter 4 of the OpenGL 3.2 (Core) Specification 72(Per-Fragment Operations and the Frame Buffer) 73 74 Modify Section 4.1.3, Multisample Fragment Operations 75 76 Modify the discussion of SampleMaski to start with "Next" instead 77 of "Finally". 78 79 Add after the discussion of SampleMaski: 80 81 Finally, a single sample location can be modified for all pixels in 82 a multi-sampled framebuffer using the following call: 83 84 void SetMultisamplefvAMD(enum pname, uint index, clampf *val); 85 86 <pname> must be SAMPLE_POSITION. <index> corresponds to the 87 sample for which the location should be set. The sample location 88 is set by passing two floating point values in <val[0]> and 89 <val[1]>, each between 0.0 and 1.0, inclusive, corresponding to the <x> 90 and <y> locations in pixel space of that sample, respectively . (0.5, 0.5) 91 thus corresponds to the pixel center. The error INVALID_VALUE is generated 92 if <index> is greater than or equal to the value of SAMPLES. 93 94 SetMultisamplefvAMD generates an INVALID_OPERATION error if the currently 95 bound framebuffer is incomplete or is the default framebuffer. 96 97 Using SetMultisamplefvAMD will cause any multisampled texture attached 98 to the currently bound FBO to use identical sample locations for all 99 of its pixels forcing <fixedsamplelocations> to TRUE. That is, using 100 GetTexLevelParameter to query TEXTURE_FIXED_SAMPLE_LOCATIONS will 101 always return TRUE if the new mechanism is used to explicitly set 102 the sample positions. 103 104 If <val> is NULL, <index> is ignored and all sample positions are returned 105 to their default values. 106 107 The subpixel range [0,1] is discretized based on the implementation- 108 dependent value of SUBSAMPLE_DISTANCE_AMD. GetFloatv can be used with 109 SUBSAMPLE_DISTANCE_AMD as the pname parameter to query the subpixel 110 precision, which is the same for both the vertical and horizontal 111 directions. Given two sample positions (x0, y0) and (x1, y1), one can make 112 sure they don't fall in the same subpixel if 113 114 abs(x0-x1) >= ssd and abs(y0-y1) >= ssd, 115 116 where ssd is the float value returned when querying SUBSAMPLE_DISTANCE_AMD. 117 118 The quantized sample positions may be queried by calling GetMultisamplefv. 119 120Additions to Chapter 5 of the OpenGL 3.2 (Core) Specification (Special Functions) 121 122 None. 123 124Additions to Chapter 6 of the OpenGL 3.2 (Core) Specification (State and 125State Requests) 126 127 None. 128 129GLX Protocol 130 131 None. 132 133Errors 134 135 The error INVALID_VALUE is generated by SetMultisamplefvAMD if index 136 is greater than or equal to the value of SAMPLES. 137 138 The error INVALID_OPERATION is generated by SetMultisamplefvAMD if 139 the currently bound framebuffer is the default framebuffer. 140 141 The error INVALID_OPERATION is generated by SetMultisamplefvAMD if 142 the currently bound framebuffer is incomplete. 143 144New State 145 146 None. 147 148New Implementation Dependent State 149 150 Add to Table 6.12, Multisampling, p.277: 151 152 Get Value Type Get Command Value Description Sec. 153 --------- ------- ----------- ------- ------------------------ ------ 154 SUBSAMPLE_DISTANCE_AMD R+ GetFloatv - precision step between 4.1.3 155 subsamples 156 157Interaction with ARB_texture_multisample 158 159 If ARB_texture_multisample is not supported, remove all references to 160 TEXTURE_FIXED_SAMPLE_LOCATIONS and to <fixedsamplelocations>. Also, should 161 ARB_texture_multisample not be supported, the GetMultisamplefv entry point 162 must be added as described in the specification of ARB_texture_multisample 163 for the sake of completeness. 164 165Issues 166 167 (1) What happens if an app just sets one sample position, 168 index 3 for example? 169 170 RESOLVED: Any attachment to the bound FBO will have the index 3 171 position updated. All the rest of the positions will keep their 172 original values. Any other fbos will not be affected by this change. 173 174 (2) How does an app get back to the default state after setting 175 sample positions? 176 177 RESOLVED: SetMultisamplefvAMD(SAMPLE_POSITION, 0, NULL) will restore 178 all the sample positions to their default state. 179 180 (3) Should we also expose the precision? An app can use it in setting 181 sample positions? 182 183 RESOLVED: SUBSAMPLE_DISTANCE_AMD is added as a new token. It can be used 184 by GetFloatv to query the precision step, which will be the same for 185 both the vertical and horizontal directions. The subpixel range [0,1] 186 is discretized based on the value of SUBSAMPLE_DISTANCE_AMD. Let ssd be the 187 float value returned when SUBSAMPLE_DISTANCE_AMD is queried, then one can 188 infer the subpixilization to be 1/ssd+1. For example, if ssd = 0.06667 189 then the pixel is subdivided into 1/0.0667+1=16 subpixels in each 190 dimension. 191 192 One can also avoid using sample positions that would map to the same 193 subpixel. A coordinate c will map to the greatest multiple of ssd that 194 is less or equal to c. For example, given two sample positions, (x0, y0) 195 and (x1, y1), if abs(x1-x0) < ssd and abs(y1-y0) < ssd, then both points 196 will map to the same subpixel, which means the application might want to 197 substitute one of these positions with another that is not redundant. 198 Using numerical values as an example, let a=(0.201, 0.0) and b=(0.25, 0.5) 199 be sample positions and ssd = 0.06667. Both the x-coordinate values 0.201 200 and 0.25 fall between 0.06667*3=0.2 and 0.06667*4=0.26667 and would 201 therefore map to the same value of 0.2. The y-coordinates also map to the 202 same value of 0 because they both belong in the range [0, 0.06667). This 203 means the two points are redundant. Therefore, the application should 204 choose a different point c=(0.3, 0.45) for example. c would be a good 205 choice because the distance between its x-coordinate and a's x-coordinate 206 is greater than ssd, that is 0.3-0.201 > 0.06667. 207 208 (4) Aside from evaluating the above equations, how can an application tell 209 what subsample positions the hardware is using? 210 211 RESOLVED: GetMultisamplefv will return the quantized sample positions, 212 not the original positions sent to SetMultisamplefvAMD. 213 214Revision History 215 216 Rev. Date Author Changes 217 ---- -------- -------- ----------------------------------------- 218 7 4/06/11 gsellers Clean up for posting on public registry. 219 6 6/30/10 gsellers Assign enumerant value for SUBSAMPLE_DISTANCE_AMD. 220 5 3/18/10 malnasse Generate INVALID_OPERATION error if attempting 221 to set sample positions for an incomplete framebuffer 222 4 2/23/10 malnasse Generate INVALID_OPERATION error if attempting 223 to set sample positions for the default framebuffer 224 3 2/05/10 gsellers Minor cleanup. Submission to AMD repository. 225 2 2/02/10 malnasse - Added a mechanism to restore the sample 226 positions to their default state. 227 - Added the issues section. 228 - Added new token to help query the subsample precision 229 1 1/27/10 malnasse First revision. 230 231 232