blob: 293a9d21d5604504045d6cf9d72bf53d351ff12c [file] [log] [blame]
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
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: June 11, 2015
Revision: 4
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 <pname> 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 <pname> 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 <pname> 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 <target>." into "An INVALID_OPERATION error is generated if the
default framebuffer is bound to <target> and <pname> 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 <target>." into "An INVALID_OPERATION error is generated if the
default framebuffer is bound to <target> and <pname> 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);
<target> or <framebuffer> selects the framebuffer whose programmable
sample locations are modified. There are <N> pairs of programmable sample
locations values in a framebuffer, where <N> 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
<count> pairs of values in <v> and update locations for samples <start> to
<start>+<count>-1. The location for sample <i> is taken from
v[2*(i-start)] and v[2*(i-start)+1].
Errors:
An INVALID_VALUE error is generated if the sum of <start> and <count> 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);
<index> 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 <pname> is SAMPLE_LOCATION_ARB (aliasing SAMPLE_POSITION),
a default sample location is returned and <index> must be less than
the value of SAMPLES. If <pname> is PROGRAMMABLE_SAMPLE_LOCATION_ARB,
a programmable sample location is returned and <index> 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 <target> is not
DRAW_FRAMEBUFFER, READ_FRAMEBUFFER, or FRAMEBUFFER.
An INVALID_OPERATION error is generated by
NamedFramebufferSampleLocationsfvARB if <framebuffer> is not
the name of an existing framebuffer object.
An INVALID_VALUE error is generated if <pname> is SAMPLE_LOCATION_ARB
and <index> is greater than or equal to the value of SAMPLES.
An INVALID_VALUE error is generated if <pname> is
PROGRAMMABLE_SAMPLE_LOCATION_ARB and <index> is greater than or equal
to the value of PROGRAMMABLE_SAMPLE_LOCATION_TABLE_SIZE_ARB.
An INVALID_ENUM error is generated if <pname> is not
SAMPLE_LOCATION_ARB or PROGRAMMABLE_SAMPLE_LOCATION_ARB.
Programmable sample locations are enabled by calling FramebufferParameteri
with a <pname> of FRAMEBUFFER_PROGRAMMABLE_SAMPLE_LOCATIONS_ARB and a
non-zero value of <param>. 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 <pname> 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 = <window x coordinate> mod grid_x;
pixel_y = <window y coordinate> 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.
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 <start> and <count> is
greater than PROGRAMMABLE_SAMPLE_LOCATION_TABLE_SIZE_ARB.
INVALID_VALUE is generated by GetMultisamplefv if <pname> is
PROGRAMMABLE_SAMPLE_LOCATION_ARB and <index> 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.