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: June 11, 2015 42 Revision: 4 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 294New Implementation Dependent State 295 296 Minimum 297 Get Value Type Get Command Value Description Sec. 298 --------- ------- ----------- ------- ------------------------ ------ 299 PROGRAMMABLE_SAMPLE_- Z+ GetIntegerv 2 Size of programmable sample 14.3.1 300 LOCATION_TABLE_SIZE_ARB location table 301 302New State 303 304 Table 23.84 (Framebuffer Dependent Values): 305 306 Get Value Get Command Type Minimum Value Description Sec. Attribute 307 --------- ----------- ---- ------------- ----------- ---- --------- 308 SAMPLE_LOCATION_SUBPIXEL_BITS_ARB GetIntegerv Z+ 4 Precision of sample 14.3.1 - 309 locations 310 SAMPLE_LOCATION_PIXEL_GRID_WIDTH_ARB GetIntegerv Z+ 1 Size of programmable 14.3.1 - 311 location grid 312 SAMPLE_LOCATION_PIXEL_GRID_HEIGHT_ARB GetIntegerv Z+ 1 Size of programmable 14.3.1 - 313 location grid 314 SAMPLE_LOCATION_ARB GetMultisamplefv n*2*R[0,1] impl-dependent Default sample 14.3.1 - 315 positions 316 Table 23.30. (Framebuffer): 317 318 Get Value Get Command Type Initial Value Description Sec. Attribute 319 --------- ----------- ---- ------------- ----------- ---- --------- 320 FRAMEBUFFER_PROGRAMMABLE_- GetFramebuffer- B FALSE Enable programmable 14.3.1 - 321 SAMPLE_LOCATIONS_ARB Parameteriv sample locations 322 FRAMEBUFFER_SAMPLE_LOCATION_- GetFramebuffer- B FALSE Enable varying 14.3.1 - 323 PIXEL_GRID_ARB Parameteriv locations per pixel 324 PROGRAMMABLE_SAMPLE_LOCATION_ARB GetMultisamplefv n*2*R[0,1] (0.5,0.5) Programmable sample 14.3.1 - 325 locations 326 327 328Additions to the AGL/GLX/WGL Specifications 329 330 None. 331 332GLX Protocol 333 334 None. 335 336Modifications to the OpenGL Shading Language Specification, Version 4.50 337 338 None. 339 340Errors 341 342 INVALID_VALUE is generated by FramebufferSampleLocationsfvARB or 343 NamedFramebufferSampleLocationsfvARB if the sum of <start> and <count> is 344 greater than PROGRAMMABLE_SAMPLE_LOCATION_TABLE_SIZE_ARB. 345 346 INVALID_VALUE is generated by GetMultisamplefv if <pname> is 347 PROGRAMMABLE_SAMPLE_LOCATION_ARB and <index> is greater than or equal to 348 the value of PROGRAMMABLE_SAMPLE_LOCATION_TABLE_SIZE_ARB. 349 350 Some errors in the original specification are relaxed to allow for new 351 functionality provided by this extension (e.g., allowing programmable 352 sample location framebuffer parameters to be set on the default 353 framebuffer). 354 355Interactions with OpenGL ES 3.1 356 357 If implemented in OpenGL ES 3.1, remove references to GetDoublev, 358 DrawPixels, CopyPixels and GetTexImage. 359 360Issues 361 362 (1) Why is SAMPLE_LOCATION_ARB added? 363 364 RESOLVED: Prior to the NV_explicit_multisample spec (and its incorporation 365 into ARB_texture_multisample), the spec used the word "location" to 366 describe the placement of the sample within a pixel, rather than 367 "position". This alias of SAMPLE_POSITION is added to return to that 368 convention. 369 370 (2) How should values that depend on the number of samples be handled for 371 incomplete framebuffers? 372 373 RESOLVED: Return zero. Other such queries (e.g. RED_BITS) are undefined 374 but do not generate an error. Let's be more well-defined, but still not 375 generate an error. 376 377 (3) Should programmable sample locations affect non-multisample rendering? 378 379 RESOLVED: No, the programmable sample locations only apply to multisample 380 rasterization rules. Non-multisample rasterization is generally defined by 381 rules involving "fragment centers" or (for lines) a diamond around the 382 fragment center. Multisample rasterization is defined by rules involving 383 sample points being inside or outside of a region defined by the primitive. 384 Thus, only multisample rasterization rules are affected by modifying the 385 sample locations. 386 387 (4) How does this extension differ from AMD_sample_positions? 388 389 RESOLVED: There are a few differences between this extension and 390 AMD_sample_positions: 391 392 - This extension allows the sample locations to vary per-pixel within a 393 grid of adjacent pixels. 394 395 - This extension specifies some limitations on texturing on various copy 396 operations when a source image was generated with programmable 397 locations, or to existing samples the framebuffer when the sample 398 locations change. It also provides an explicit "resolve" operation that 399 allows one to ensure that correct values are stored in all samples when 400 non-framebuffer operations not supporting the programmable locations are 401 used. This issue is not explicitly handled in the AMD extension. 402 403 - This extension has explicit framebuffer parameters enabling programmable 404 sample locations and multi-pixel grid support. The AMD extension lets 405 you effectively delete all programmable sample locations and revert to 406 default locations via programming a new location using a NULL pointer. 407 408 - The sample locations in this extension are explicitly framebuffer object 409 state, with separate state available for the default framebuffer (zero). 410 It's unclear from the AMD extension whether the state is global or per 411 framebuffer object, though a note in comment (1) ("Any other fbos will 412 not be affected by this change") suggests it might also be framebuffer 413 object state. 414 415 (5) Can PROGRAMMABLE_SAMPLE_LOCATION_TABLE_SIZE_ARB be less than SAMPLES 416 for a specific framebuffer? 417 418 RESOLVED: In order to allow the application to specify the sample 419 locations for all samples, the implementation must make the size of 420 PROGRAMMABLE_SAMPLE_LOCATION_TABLE_SIZE_ARB at least as big as the 421 framebuffer SAMPLES size. It would be invalid for an implementation 422 to report a PROGRAMMABLE_SAMPLE_LOCATION_TABLE_SIZE_ARB less than 423 any framebuffer SAMPLES size. 424 425Revision History 426 427 Revision 1 428 - Branch from NV_sample_locations 429 430 Revision 2 pdaniell 5/26 431 - Rename ResolveDepthValuesARB() to EvaluateDepthValuesARB(). 432 433 Revision 3 ewerness 6/5 434 - Complete rename of ResolveDepthValuesARB() to EvaluateDepthValuesARB(). 435 436 Revision 4 pdaniell 6/11 437 - Add issue (5) to cover question in bug 14100. 438