1Name 2 3 NV_sample_locations 4 5Name Strings 6 7 GL_NV_sample_locations 8 9Contact 10 11 Jeff Bolz, NVIDIA Corporation (jbolz 'at' nvidia.com) 12 13Contributors 14 15 Pat Brown, NVIDIA 16 Mathias Heyer, NVIDIA 17 18Status 19 20 Shipping 21 22Version 23 24 Last Modified Date: March 27, 2015 25 Revision: 2 26 27Number 28 29 OpenGL Extension #472 30 OpenGL ES Extension #235 31 32Dependencies 33 34 This extension is written against the OpenGL 4.3 specification 35 (Compatibility Profile). 36 37 This extension interacts with OpenGL ES 3.1. 38 39Overview 40 41 This extension allows an application to modify the locations of samples 42 within a pixel used in multisample rasterization. Additionally, it allows 43 applications to specify different sample locations for each pixel in a 44 group of adjacent pixels, which may increase antialiasing quality 45 (particularly if a custom resolve shader is used that takes advantage of 46 these different locations). 47 48 It is common for implementations to optimize the storage of depth values 49 by storing values that can be used to reconstruct depth at each sample 50 location, rather than storing separate depth values for each sample. For 51 example, the depth values from a single triangle can be represented using 52 plane equations. When the depth value for a sample is needed, it is 53 automatically evaluated at the sample location. Modifying the sample 54 locations causes the reconstruction to no longer evaluate the same depth 55 values as when the samples were originally generated. This extension 56 provides a command to "resolve" and store per-sample depth values using 57 the currently programmed sample locations, which allows the application to 58 manage this issue if/when necessary. 59 60 The programmable sample locations are used during rasterization and for 61 evaluation of depth functions during normal geometric rendering. The 62 programmable locations are associated with a framebuffer object rather 63 than an individual depth buffer, so if the depth buffer is used as a 64 texture the texture sampling may be done at the standard sample 65 locations. Additionally, commands that do not render geometric primitives 66 (e.g. ReadPixels, BlitFramebuffer, CopyTexSubImage2D, etc.) may use the 67 standard sample locations to resolve depth functions rather than the 68 programmable locations. If a single depth buffer is used at different 69 times with different sample locations, the depth functions may be 70 interpreted using the current sample locations. 71 72New Procedures and Functions 73 74 void FramebufferSampleLocationsfvNV(enum target, uint start, 75 sizei count, const float *v); 76 void NamedFramebufferSampleLocationsfvNV(uint framebuffer, uint start, 77 sizei count, const float *v); 78 79 void ResolveDepthValuesNV(void); 80 81New Tokens 82 83 Accepted by the <pname> parameter of GetBooleanv, GetIntegerv, 84 GetInteger64v, GetFloatv, and GetDoublev: 85 86 SAMPLE_LOCATION_SUBPIXEL_BITS_NV 0x933D 87 SAMPLE_LOCATION_PIXEL_GRID_WIDTH_NV 0x933E 88 SAMPLE_LOCATION_PIXEL_GRID_HEIGHT_NV 0x933F 89 PROGRAMMABLE_SAMPLE_LOCATION_TABLE_SIZE_NV 0x9340 90 91 Accepted by the <pname> parameter of GetMultisamplefv: 92 93 // Alias of SAMPLE_POSITION. Before NV_expms, the spec used "location". 94 SAMPLE_LOCATION_NV 0x8E50 95 PROGRAMMABLE_SAMPLE_LOCATION_NV 0x9341 96 97 Accepted by the <pname> parameter of FramebufferParameteri, 98 GetFramebufferParameteriv: 99 100 FRAMEBUFFER_PROGRAMMABLE_SAMPLE_LOCATIONS_NV 0x9342 101 FRAMEBUFFER_SAMPLE_LOCATION_PIXEL_GRID_NV 0x9343 102 103Additions to Chapter 14 of the OpenGL 4.3 (Compatibility Profile) Specification 104(Fixed-Function Primitive Assembly and Rasterization) 105 106 Modify Section 9.2.1 (Framebuffer Object Parameters), p. 297 107 108 Change the error: 109 110 "An INVALID_OPERATION error is generated if the default framebuffer is 111 bound to <target>." into "An INVALID_OPERATION error is generated if the 112 default framebuffer is bound to <target> and <pname> is neither 113 FRAMEBUFFER_PROGRAMMABLE_SAMPLE_LOCATIONS_NV nor 114 FRAMEBUFFER_SAMPLE_LOCATION_PIXEL_GRID_NV." 115 116 Modify Section 9.2.3 (Framebuffer Object Queries), p. 298 117 118 Change the error: 119 120 "An INVALID_OPERATION error is generated if the default framebuffer is 121 bound to <target>." into "An INVALID_OPERATION error is generated if the 122 default framebuffer is bound to <target> and <pname> is neither 123 FRAMEBUFFER_PROGRAMMABLE_SAMPLE_LOCATIONS_NV nor 124 FRAMEBUFFER_SAMPLE_LOCATION_PIXEL_GRID_NV." 125 126 Modify Section 14.3.1 (Multisampling), p. 478 127 128 Remove the paragraph describing "GetMultisamplefv", and append the 129 following to the section. 130 131 Each framebuffer has a set of default sample locations, depending on the 132 number of samples in the attachments or the value of FRAMEBUFFER_DEFAULT_- 133 SAMPLES (for framebuffer objects) or the number of samples in the pixel 134 format (for the default framebuffer). Each framebuffer also has a set of 135 programmable sample locations, which may be used instead of the default 136 sample locations. The programmable sample locations are controlled by the 137 commands: 138 139 void FramebufferSampleLocationsfvNV(enum target, uint start, 140 sizei count, const float *v); 141 void NamedFramebufferSampleLocationsfvNV(uint framebuffer, uint start, 142 sizei count, const float *v); 143 144 <target> or <framebuffer> selects the framebuffer whose programmable 145 sample locations are modified. There are <N> pairs of programmable sample 146 locations values in a framebuffer, where <N> is the value of 147 PROGRAMMABLE_SAMPLE_LOCATION_TABLE_SIZE_NV. Each programmable sample 148 location is specified as a pair of floating point values in the range 149 [0,1], corresponding to the x and y locations respectively in GL pixel 150 space. (0.5, 0.5) thus corresponds to the pixel center. Sample locations 151 outside of [0,1] result in undefined behavior. These commands accept 152 <count> pairs of values in <v> and update locations for samples <start> to 153 <start>+<count>-1. The location for sample <i> is taken from 154 v[2*(i-start)] and v[2*(i-start)+1]. 155 156 Errors: 157 158 An INVALID_VALUE error is generated if the sum of <start> and <count> is 159 greater than PROGRAMMABLE_SAMPLE_LOCATION_TABLE_SIZE_NV. 160 161 Default and programmable sample locations may be queried with the command: 162 163 void GetMultisamplefv(enum pname, uint index, float *val); 164 165 <index> corresponds to which sample location should be returned, and the 166 sample location is returned as two floating-point values in val[0] and 167 val[1]. If <pname> is SAMPLE_LOCATION_NV (aliasing SAMPLE_POSITION), 168 a default sample location is returned and <index> must be less than 169 the value of SAMPLES. If <pname> is PROGRAMMABLE_SAMPLE_LOCATION_NV, 170 a programmable sample location is returned and <index> must be less 171 than the value of PROGRAMMABLE_SAMPLE_LOCATION_TABLE_SIZE_NV. 172 173 Sample locations are rounded on use to the precision indicated by the value 174 of SAMPLE_LOCATION_SUBPIXEL_BITS_NV (i.e. rounded to the nearest 175 2^{-subpixelbits}). This precision may depend on the number of samples in 176 the framebuffer. The initial programmable sample locations are all 177 (0.5,0.5). 178 179 Errors: 180 181 An INVALID_ENUM error is generated if <target> is not 182 DRAW_FRAMEBUFFER, READ_FRAMEBUFFER, or FRAMEBUFFER. 183 184 An INVALID_OPERATION error is generated by 185 NamedFramebufferSampleLocationsfvNV if <framebuffer> is not 186 the name of an existing framebuffer object. 187 188 An INVALID_VALUE error is generated if <pname> is SAMPLE_LOCATION_NV 189 and <index> is greater than or equal to the value of SAMPLES. 190 191 An INVALID_VALUE error is generated if <pname> is 192 PROGRAMMABLE_SAMPLE_LOCATION_NV and <index> is greater than or equal 193 to the value of PROGRAMMABLE_SAMPLE_LOCATION_TABLE_SIZE_NV. 194 195 An INVALID_ENUM error is generated if <pname> is not 196 SAMPLE_LOCATION_NV or PROGRAMMABLE_SAMPLE_LOCATION_NV. 197 198 Programmable sample locations are enabled by calling FramebufferParameteri 199 with a <pname> of FRAMEBUFFER_PROGRAMMABLE_SAMPLE_LOCATIONS_NV and a 200 non-zero value of <param>. The initial value of FRAMEBUFFER_PROGRAMMABLE_- 201 SAMPLE_LOCATIONS_NV is zero. 202 203 Programmable sample locations can vary across pixels, based on the pixel x 204 and y coordinate. A framebuffer has a sample location pixel grid which may 205 depend on the number of samples. This grid size can be queried by calling 206 GetIntegerv with a <pname> of SAMPLE_LOCATION_PIXEL_GRID_WIDTH_NV and 207 SAMPLE_LOCATION_PIXEL_GRID_HEIGHT_NV, which returns the grid dimensions for 208 the draw framebuffer. 209 210 If FRAMEBUFFER_PROGRAMMABLE_SAMPLE_LOCATIONS_NV is enabled and the 211 framebuffer parameter FRAMEBUFFER_SAMPLE_LOCATION_PIXEL_GRID_NV is enabled 212 (non-zero), sample locations are selected as follows: 213 214 grid_x = value of SAMPLE_LOCATION_PIXEL_GRID_WIDTH_NV; 215 grid_y = value of SAMPLE_LOCATION_PIXEL_GRID_HEIGHT_NV; 216 217 pixel_x = <window x coordinate> mod grid_x; 218 pixel_y = <window y coordinate> mod grid_y; 219 220 num_samples = value of SAMPLES; 221 sample_i = (pixel_y*grid_x + pixel_x)*num_samples + sample_index; 222 223 float *table = FRAMEBUFFER_PROGRAMMABLE_SAMPLE_LOCATIONS_NV; 224 sample_location.xy = (table[2*sample_i], table[2*sample_i+1]); 225 226 If FRAMEBUFFER_PROGRAMMABLE_SAMPLE_LOCATIONS_NV is enabled and 227 FRAMEBUFFER_SAMPLE_LOCATION_PIXEL_GRID_NV is disabled, sample locations are 228 selected as follows: 229 230 sample_i = sample_index; 231 232 float *table = FRAMEBUFFER_PROGRAMMABLE_SAMPLE_LOCATIONS_NV; 233 sample_location.xy = (table[2*sample_i], table[2*sample_i+1]); 234 235 If a framebuffer is incomplete, querying the value of 236 SAMPLE_LOCATION_SUBPIXEL_BITS_NV, SAMPLE_LOCATION_PIXEL_GRID_WIDTH_NV, and 237 SAMPLE_LOCATION_PIXEL_GRID_HEIGHT_NV will return zero. 238 239 Add new Subsection 14.3.1.X (Resolving Depth Values) 240 241 It is common for implementations to optimize the storage of depth values 242 by storing values that can be used to reconstruct depth at each sample 243 location, rather than storing separate depth values for each sample. For 244 example, the depth values from a single triangle can be represented using 245 plane equations. When the depth value for a sample is needed, it is 246 automatically evaluated at the sample location. Modifying the sample 247 locations causes the reconstruction to no longer evaluate the same depth 248 values as when the samples were originally generated. The choice of using 249 separate depth values for each sample or some other reconstruction method 250 is implementation-dependent and may not be queried. 251 252 If per-sample depth values need to be reconstructed, some commands may 253 evaluate depth values using default sample locations even if programmable 254 sample locations are enabled. This evaluation can occur either when 255 reading sample values or when updating one sample requires the 256 implementation to reconstruct depth values for a group of neighboring 257 samples. These commands include ReadPixels, DrawPixels, CopyPixels, 258 GetTexImage, CopyTexImage, CopyTexSubImage, TexImage, TexSubImage, and 259 BlitFramebuffer. Texturing from a depth texture whose values need to be 260 reconstructed may also evaluate depth functions as the default sample 261 locations. 262 263 The command 264 265 void ResolveDepthValuesNV(); 266 267 evaluates depth values for all samples in the current depth buffer 268 (subject to the pixel ownership and scissor tests) and stores each value 269 in the depth buffer. This can be used to ensure that later accesses will 270 use depth values consistent with the sample locations used when the 271 samples were generated. If the current framebuffer has no depth buffer, 272 ResolveDepthValuesNV will have no effect. 273 274 275New Implementation Dependent State 276 277 Minimum 278 Get Value Type Get Command Value Description Sec. 279 --------- ------- ----------- ------- ------------------------ ------ 280 PROGRAMMABLE_SAMPLE_- Z+ GetIntegerv 2 Size of programmable sample 14.3.1 281 LOCATION_TABLE_SIZE_NV location table 282 283New State 284 285 Table 23.84 (Framebuffer Dependent Values): 286 287 Get Value Get Command Type Minimum Value Description Sec. Attribute 288 --------- ----------- ---- ------------- ----------- ---- --------- 289 SAMPLE_LOCATION_SUBPIXEL_BITS_NV GetIntegerv Z+ 4 Precision of sample 14.3.1 - 290 locations 291 SAMPLE_LOCATION_PIXEL_GRID_WIDTH_NV GetIntegerv Z+ 1 Size of programmable 14.3.1 - 292 location grid 293 SAMPLE_LOCATION_PIXEL_GRID_HEIGHT_NV GetIntegerv Z+ 1 Size of programmable 14.3.1 - 294 location grid 295 SAMPLE_LOCATION_NV GetMultisamplefv n*2*R[0,1] impl-dependent Default sample 14.3.1 - 296 positions 297 Table 23.30. (Framebuffer): 298 299 Get Value Get Command Type Initial Value Description Sec. Attribute 300 --------- ----------- ---- ------------- ----------- ---- --------- 301 FRAMEBUFFER_PROGRAMMABLE_- GetFramebuffer- B FALSE Enable programmable 14.3.1 - 302 SAMPLE_LOCATIONS_NV Parameteriv sample locations 303 FRAMEBUFFER_SAMPLE_LOCATION_- GetFramebuffer- B FALSE Enable varying 14.3.1 - 304 PIXEL_GRID_NV Parameteriv locations per pixel 305 PROGRAMMABLE_SAMPLE_LOCATION_NV GetMultisamplefv n*2*R[0,1] (0.5,0.5) Programmable sample 14.3.1 - 306 locations 307 308 309Additions to the AGL/GLX/WGL Specifications 310 311 None. 312 313GLX Protocol 314 315 None. 316 317Modifications to the OpenGL Shading Language Specification, Version 4.30 318 319 None. 320 321Errors 322 323 INVALID_VALUE is generated by FramebufferSampleLocationsfvNV or 324 NamedFramebufferSampleLocationsfvNV if the sum of <start> and <count> is 325 greater than PROGRAMMABLE_SAMPLE_LOCATION_TABLE_SIZE_NV. 326 327 INVALID_VALUE is generated by GetMultisamplefv if <pname> is 328 PROGRAMMABLE_SAMPLE_LOCATION_NV and <index> is greater than or equal to 329 the value of PROGRAMMABLE_SAMPLE_LOCATION_TABLE_SIZE_NV. 330 331 Some errors in the original specification are relaxed to allow for new 332 functionality provided by this extension (e.g., allowing programmable 333 sample location framebuffer parameters to be set on the default 334 framebuffer). 335 336Interactions with OpenGL ES 3.1 337 338 If implemented in OpenGL ES 3.1, remove references to GetDoublev, 339 DrawPixels, CopyPixels and GetTexImage. 340 341Issues 342 343 (1) Why is SAMPLE_LOCATION_NV added? 344 345 RESOLVED: Prior to the NV_explicit_multisample spec (and its incorporation 346 into ARB_texture_multisample), the spec used the word "location" to 347 describe the placement of the sample within a pixel, rather than 348 "position". This alias of SAMPLE_POSITION is added to return to that 349 convention. 350 351 (2) How should values that depend on the number of samples be handled for 352 incomplete framebuffers? 353 354 RESOLVED: Return zero. Other such queries (e.g. RED_BITS) are undefined 355 but do not generate an error. Let's be more well-defined, but still not 356 generate an error. 357 358 (3) Should programmable sample locations affect non-multisample rendering? 359 360 RESOLVED: No, the programmable sample locations only apply to multisample 361 rasterization rules. Non-multisample rasterization is generally defined by 362 rules involving "fragment centers" or (for lines) a diamond around the 363 fragment center. Multisample rasterization is defined by rules involving 364 sample points being inside or outside of a region defined by the primitive. 365 Thus, only multisample rasterization rules are affected by modifying the 366 sample locations. 367 368 (4) How does this extension differ from AMD_sample_positions? 369 370 RESOLVED: There are a few differences between this extension and 371 AMD_sample_positions: 372 373 - This extension allows the sample locations to vary per-pixel within a 374 grid of adjacent pixels. 375 376 - This extension specifies some limitations on texturing on various copy 377 operations when a source image was generated with programmable 378 locations, or to existing samples the framebuffer when the sample 379 locations change. It also provides an explicit "resolve" operation that 380 allows one to ensure that correct values are stored in all samples when 381 non-framebuffer operations not supporting the programmable locations are 382 used. This issue is not explicitly handled in the AMD extension. 383 384 - This extension has explicit framebuffer parameters enabling programmable 385 sample locations and multi-pixel grid support. The AMD extension lets 386 you effectively delete all programmable sample locations and revert to 387 default locations via programming a new location using a NULL pointer. 388 389 - The sample locations in this extension are explicitly framebuffer object 390 state, with separate state available for the default framebuffer (zero). 391 It's unclear from the AMD extension whether the state is global or per 392 framebuffer object, though a note in comment (1) ("Any other fbos will 393 not be affected by this change") suggests it might also be framebuffer 394 object state. 395 396Revision History 397 398 Revision 2, 2015/03/27 399 - Add ES interactions 400 401 Revision 1 402 - Internal revisions. 403