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