Name ARB_sample_locations Name Strings GL_ARB_sample_locations Contact Piers Daniell, NVIDIA Corporation (pdaniell 'at' nvidia.com) Contributors Jeff Bolz, NVIDIA Pat Brown, NVIDIA Mathias Heyer, NVIDIA Notice Copyright (c) 2015 The Khronos Group Inc. Copyright terms at http://www.khronos.org/registry/speccopyright.html Specification Update Policy Khronos-approved extension specifications are updated in response to issues and bugs prioritized by the Khronos OpenGL Working Group. For extensions which have been promoted to a core Specification, fixes will first appear in the latest version of that core Specification, and will eventually be backported to the extension document. This policy is described in more detail at https://www.khronos.org/registry/OpenGL/docs/update_policy.php Status Complete. Approved by the ARB on June 26, 2015. Ratified by the Khronos Board of Promoters on August 7, 2015. Version Last Modified Date: March 16, 2024 Revision: 5 Number ARB Extension #181 Dependencies This extension is written against the OpenGL 4.5 specification (Compatibility Profile). This extension interacts with OpenGL ES 3.1. Overview This extension allows an application to modify the locations of samples within a pixel used in multisample rasterization. Additionally, it allows applications to specify different sample locations for each pixel in a group of adjacent pixels, which may increase antialiasing quality (particularly if a custom resolve shader is used that takes advantage of these different locations). It is common for implementations to optimize the storage of depth values by storing values that can be used to reconstruct depth at each sample location, rather than storing separate depth values for each sample. For example, the depth values from a single triangle can be represented using plane equations. When the depth value for a sample is needed, it is automatically evaluated at the sample location. Modifying the sample locations causes the reconstruction to no longer evaluate the same depth values as when the samples were originally generated. This extension provides a command to "evaluate" and store per-sample depth values using the currently programmed sample locations, which allows the application to manage this issue if/when necessary. The programmable sample locations are used during rasterization and for evaluation of depth functions during normal geometric rendering. The programmable locations are associated with a framebuffer object rather than an individual depth buffer, so if the depth buffer is used as a texture the texture sampling may be done at the standard sample locations. Additionally, commands that do not render geometric primitives (e.g. ReadPixels, BlitFramebuffer, CopyTexSubImage2D, etc.) may use the standard sample locations to evaluate depth functions rather than the programmable locations. If a single depth buffer is used at different times with different sample locations, the depth functions may be interpreted using the current sample locations. New Procedures and Functions void FramebufferSampleLocationsfvARB(enum target, uint start, sizei count, const float *v); void NamedFramebufferSampleLocationsfvARB(uint framebuffer, uint start, sizei count, const float *v); void EvaluateDepthValuesARB(); New Tokens Accepted by the parameter of GetBooleanv, GetIntegerv, GetInteger64v, GetFloatv, and GetDoublev: SAMPLE_LOCATION_SUBPIXEL_BITS_ARB 0x933D SAMPLE_LOCATION_PIXEL_GRID_WIDTH_ARB 0x933E SAMPLE_LOCATION_PIXEL_GRID_HEIGHT_ARB 0x933F PROGRAMMABLE_SAMPLE_LOCATION_TABLE_SIZE_ARB 0x9340 Accepted by the parameter of GetMultisamplefv: // Alias of SAMPLE_POSITION. Before NV_expms, the spec used "location". SAMPLE_LOCATION_ARB 0x8E50 PROGRAMMABLE_SAMPLE_LOCATION_ARB 0x9341 Accepted by the parameter of FramebufferParameteri, GetFramebufferParameteriv: FRAMEBUFFER_PROGRAMMABLE_SAMPLE_LOCATIONS_ARB 0x9342 FRAMEBUFFER_SAMPLE_LOCATION_PIXEL_GRID_ARB 0x9343 Additions to Chapter 9 of the OpenGL 4.5 (Compatibility Profile) Specification (Framebuffers and Framebuffer Objects) Modify Section 9.2.1 (Framebuffer Object Parameters), p. 330 Change the error: "An INVALID_OPERATION error is generated if the default framebuffer is bound to ." into "An INVALID_OPERATION error is generated if the default framebuffer is bound to and is neither FRAMEBUFFER_PROGRAMMABLE_SAMPLE_LOCATIONS_ARB nor FRAMEBUFFER_SAMPLE_LOCATION_PIXEL_GRID_ARB." Modify Section 9.2.3 (Framebuffer Object Queries), p. 332 Change the error: "An INVALID_OPERATION error is generated if the default framebuffer is bound to ." into "An INVALID_OPERATION error is generated if the default framebuffer is bound to and is neither FRAMEBUFFER_PROGRAMMABLE_SAMPLE_LOCATIONS_ARB nor FRAMEBUFFER_SAMPLE_LOCATION_PIXEL_GRID_ARB." Additions to Chapter 14 of the OpenGL 4.5 (Compatibility Profile) Specification (Fixed-Function Primitive Assembly and Rasterization) Modify Section 14.3.1 (Multisampling), p. 527 Remove the paragraph describing "GetMultisamplefv", and append the following to the section. Each framebuffer has a set of default sample locations, depending on the number of samples in the attachments or the value of FRAMEBUFFER_DEFAULT_- SAMPLES (for framebuffer objects) or the number of samples in the pixel format (for the default framebuffer). Each framebuffer also has a set of programmable sample locations, which may be used instead of the default sample locations. The programmable sample locations are controlled by the commands: void FramebufferSampleLocationsfvARB(enum target, uint start, sizei count, const float *v); void NamedFramebufferSampleLocationsfvARB(uint framebuffer, uint start, sizei count, const float *v); or selects the framebuffer whose programmable sample locations are modified. There are pairs of programmable sample locations values in a framebuffer, where is the value of PROGRAMMABLE_SAMPLE_LOCATION_TABLE_SIZE_ARB. Each programmable sample location is specified as a pair of floating point values in the range [0,1], corresponding to the x and y locations respectively in GL pixel space. (0.5, 0.5) thus corresponds to the pixel center. Sample locations outside of [0,1] result in undefined behavior. These commands accept pairs of values in and update locations for samples to +-1. The location for sample is taken from v[2*(i-start)] and v[2*(i-start)+1]. Errors: An INVALID_VALUE error is generated if the sum of and is greater than PROGRAMMABLE_SAMPLE_LOCATION_TABLE_SIZE_ARB. Default and programmable sample locations may be queried with the command: void GetMultisamplefv(enum pname, uint index, float *val); corresponds to which sample location should be returned, and the sample location is returned as two floating-point values in val[0] and val[1]. If is SAMPLE_LOCATION_ARB (aliasing SAMPLE_POSITION), a default sample location is returned and must be less than the value of SAMPLES. If is PROGRAMMABLE_SAMPLE_LOCATION_ARB, a programmable sample location is returned and must be less than the value of PROGRAMMABLE_SAMPLE_LOCATION_TABLE_SIZE_ARB. Sample locations are rounded on use to the precision indicated by the value of SAMPLE_LOCATION_SUBPIXEL_BITS_ARB (i.e. rounded to the nearest 2^{-subpixelbits}). This precision may depend on the number of samples in the framebuffer. The initial programmable sample locations are all (0.5,0.5). Errors: An INVALID_ENUM error is generated if is not DRAW_FRAMEBUFFER, READ_FRAMEBUFFER, or FRAMEBUFFER. An INVALID_OPERATION error is generated by NamedFramebufferSampleLocationsfvARB if is not the name of an existing framebuffer object. An INVALID_VALUE error is generated if is SAMPLE_LOCATION_ARB and is greater than or equal to the value of SAMPLES. An INVALID_VALUE error is generated if is PROGRAMMABLE_SAMPLE_LOCATION_ARB and is greater than or equal to the value of PROGRAMMABLE_SAMPLE_LOCATION_TABLE_SIZE_ARB. An INVALID_ENUM error is generated if is not SAMPLE_LOCATION_ARB or PROGRAMMABLE_SAMPLE_LOCATION_ARB. Programmable sample locations are enabled by calling FramebufferParameteri with a of FRAMEBUFFER_PROGRAMMABLE_SAMPLE_LOCATIONS_ARB and a non-zero value of . The initial value of FRAMEBUFFER_PROGRAMMABLE_- SAMPLE_LOCATIONS_ARB is zero. Programmable sample locations can vary across pixels, based on the pixel x and y coordinate. A framebuffer has a sample location pixel grid which may depend on the number of samples. This grid size can be queried by calling GetIntegerv with a of SAMPLE_LOCATION_PIXEL_GRID_WIDTH_ARB and SAMPLE_LOCATION_PIXEL_GRID_HEIGHT_ARB, which returns the grid dimensions for the draw framebuffer. If FRAMEBUFFER_PROGRAMMABLE_SAMPLE_LOCATIONS_ARB is enabled and the framebuffer parameter FRAMEBUFFER_SAMPLE_LOCATION_PIXEL_GRID_ARB is enabled (non-zero), sample locations are selected as follows: grid_x = value of SAMPLE_LOCATION_PIXEL_GRID_WIDTH_ARB; grid_y = value of SAMPLE_LOCATION_PIXEL_GRID_HEIGHT_ARB; pixel_x = mod grid_x; pixel_y = mod grid_y; num_samples = value of SAMPLES; sample_i = (pixel_y*grid_x + pixel_x)*num_samples + sample_index; float *table = FRAMEBUFFER_PROGRAMMABLE_SAMPLE_LOCATIONS_ARB; sample_location.xy = (table[2*sample_i], table[2*sample_i+1]); If FRAMEBUFFER_PROGRAMMABLE_SAMPLE_LOCATIONS_ARB is enabled and FRAMEBUFFER_SAMPLE_LOCATION_PIXEL_GRID_ARB is disabled, sample locations are selected as follows: sample_i = sample_index; float *table = FRAMEBUFFER_PROGRAMMABLE_SAMPLE_LOCATIONS_ARB; sample_location.xy = (table[2*sample_i], table[2*sample_i+1]); If a framebuffer is incomplete, querying the value of SAMPLE_LOCATION_SUBPIXEL_BITS_ARB, SAMPLE_LOCATION_PIXEL_GRID_WIDTH_ARB, and SAMPLE_LOCATION_PIXEL_GRID_HEIGHT_ARB will return zero. Add new Subsection 14.3.1.X (Resolving Depth Values) It is common for implementations to optimize the storage of depth values by storing values that can be used to reconstruct depth at each sample location, rather than storing separate depth values for each sample. For example, the depth values from a single triangle can be represented using plane equations. When the depth value for a sample is needed, it is automatically evaluated at the sample location. Modifying the sample locations causes the reconstruction to no longer evaluate the same depth values as when the samples were originally generated. The choice of using separate depth values for each sample or some other reconstruction method is implementation-dependent and may not be queried. If per-sample depth values need to be reconstructed, some commands may evaluate depth values using default sample locations even if programmable sample locations are enabled. This evaluation can occur either when reading sample values or when updating one sample requires the implementation to reconstruct depth values for a group of neighboring samples. These commands include ReadPixels, DrawPixels, CopyPixels, GetTexImage, CopyTexImage, CopyTexSubImage, TexImage, TexSubImage, and BlitFramebuffer. Texturing from a depth texture whose values need to be reconstructed may also evaluate depth functions as the default sample locations. The command void EvaluateDepthValuesARB(); evaluates depth values for all samples in the current depth buffer (subject to the pixel ownership and scissor tests) and stores each value in the depth buffer. This can be used to ensure that later accesses will use depth values consistent with the sample locations used when the samples were generated. If the current framebuffer has no depth buffer, EvaluateDepthValuesARB will have no effect. Modify Section 15.2.2, Shader Inputs, p. 568 (insert after the paragraph describing gl_SamplePosition, p. 570) If FRAMEBUFFER_PROGRAMMABLE_SAMPLE_LOCATIONS_ARB is enabled, the value of gl_SamplePosition is undefined. New Implementation Dependent State Minimum Get Value Type Get Command Value Description Sec. --------- ------- ----------- ------- ------------------------ ------ PROGRAMMABLE_SAMPLE_- Z+ GetIntegerv 2 Size of programmable sample 14.3.1 LOCATION_TABLE_SIZE_ARB location table New State Table 23.84 (Framebuffer Dependent Values): Get Value Get Command Type Minimum Value Description Sec. Attribute --------- ----------- ---- ------------- ----------- ---- --------- SAMPLE_LOCATION_SUBPIXEL_BITS_ARB GetIntegerv Z+ 4 Precision of sample 14.3.1 - locations SAMPLE_LOCATION_PIXEL_GRID_WIDTH_ARB GetIntegerv Z+ 1 Size of programmable 14.3.1 - location grid SAMPLE_LOCATION_PIXEL_GRID_HEIGHT_ARB GetIntegerv Z+ 1 Size of programmable 14.3.1 - location grid SAMPLE_LOCATION_ARB GetMultisamplefv n*2*R[0,1] impl-dependent Default sample 14.3.1 - positions Table 23.30. (Framebuffer): Get Value Get Command Type Initial Value Description Sec. Attribute --------- ----------- ---- ------------- ----------- ---- --------- FRAMEBUFFER_PROGRAMMABLE_- GetFramebuffer- B FALSE Enable programmable 14.3.1 - SAMPLE_LOCATIONS_ARB Parameteriv sample locations FRAMEBUFFER_SAMPLE_LOCATION_- GetFramebuffer- B FALSE Enable varying 14.3.1 - PIXEL_GRID_ARB Parameteriv locations per pixel PROGRAMMABLE_SAMPLE_LOCATION_ARB GetMultisamplefv n*2*R[0,1] (0.5,0.5) Programmable sample 14.3.1 - locations Additions to the AGL/GLX/WGL Specifications None. GLX Protocol None. Modifications to the OpenGL Shading Language Specification, Version 4.50 None. Errors INVALID_VALUE is generated by FramebufferSampleLocationsfvARB or NamedFramebufferSampleLocationsfvARB if the sum of and is greater than PROGRAMMABLE_SAMPLE_LOCATION_TABLE_SIZE_ARB. INVALID_VALUE is generated by GetMultisamplefv if is PROGRAMMABLE_SAMPLE_LOCATION_ARB and is greater than or equal to the value of PROGRAMMABLE_SAMPLE_LOCATION_TABLE_SIZE_ARB. Some errors in the original specification are relaxed to allow for new functionality provided by this extension (e.g., allowing programmable sample location framebuffer parameters to be set on the default framebuffer). Interactions with OpenGL ES 3.1 If implemented in OpenGL ES 3.1, remove references to GetDoublev, DrawPixels, CopyPixels and GetTexImage. Issues (1) Why is SAMPLE_LOCATION_ARB added? RESOLVED: Prior to the NV_explicit_multisample spec (and its incorporation into ARB_texture_multisample), the spec used the word "location" to describe the placement of the sample within a pixel, rather than "position". This alias of SAMPLE_POSITION is added to return to that convention. (2) How should values that depend on the number of samples be handled for incomplete framebuffers? RESOLVED: Return zero. Other such queries (e.g. RED_BITS) are undefined but do not generate an error. Let's be more well-defined, but still not generate an error. (3) Should programmable sample locations affect non-multisample rendering? RESOLVED: No, the programmable sample locations only apply to multisample rasterization rules. Non-multisample rasterization is generally defined by rules involving "fragment centers" or (for lines) a diamond around the fragment center. Multisample rasterization is defined by rules involving sample points being inside or outside of a region defined by the primitive. Thus, only multisample rasterization rules are affected by modifying the sample locations. (4) How does this extension differ from AMD_sample_positions? RESOLVED: There are a few differences between this extension and AMD_sample_positions: - This extension allows the sample locations to vary per-pixel within a grid of adjacent pixels. - This extension specifies some limitations on texturing on various copy operations when a source image was generated with programmable locations, or to existing samples the framebuffer when the sample locations change. It also provides an explicit "resolve" operation that allows one to ensure that correct values are stored in all samples when non-framebuffer operations not supporting the programmable locations are used. This issue is not explicitly handled in the AMD extension. - This extension has explicit framebuffer parameters enabling programmable sample locations and multi-pixel grid support. The AMD extension lets you effectively delete all programmable sample locations and revert to default locations via programming a new location using a NULL pointer. - The sample locations in this extension are explicitly framebuffer object state, with separate state available for the default framebuffer (zero). It's unclear from the AMD extension whether the state is global or per framebuffer object, though a note in comment (1) ("Any other fbos will not be affected by this change") suggests it might also be framebuffer object state. (5) Can PROGRAMMABLE_SAMPLE_LOCATION_TABLE_SIZE_ARB be less than SAMPLES for a specific framebuffer? RESOLVED: In order to allow the application to specify the sample locations for all samples, the implementation must make the size of PROGRAMMABLE_SAMPLE_LOCATION_TABLE_SIZE_ARB at least as big as the framebuffer SAMPLES size. It would be invalid for an implementation to report a PROGRAMMABLE_SAMPLE_LOCATION_TABLE_SIZE_ARB less than any framebuffer SAMPLES size. Revision History Revision 1 - Branch from NV_sample_locations Revision 2 pdaniell 5/26 - Rename ResolveDepthValuesARB() to EvaluateDepthValuesARB(). Revision 3 ewerness 6/5 - Complete rename of ResolveDepthValuesARB() to EvaluateDepthValuesARB(). Revision 4 pdaniell 6/11 - Add issue (5) to cover question in bug 14100. Revision 5 alyssa 3/16 - Clarify interaction with gl_SamplePosition.