1Name
2
3    NV_texture_multisample
4
5Name Strings
6
7    GL_NV_texture_multisample
8
9Contact
10
11    Jeff Bolz, NVIDIA Corporation (jbolz 'at' nvidia.com)
12
13Status
14
15    Shipping on NVIDIA GPUs (GeForce 8 and up) since Release 190.
16
17Version
18
19    Last Modified Date:         09/10/09
20    Revision:                   2
21
22Number
23
24    403
25
26Dependencies
27
28    OpenGL 2.0 is required.
29
30    This extension is written against the OpenGL 3.1 specification and the 
31    NV_gpu_program4 extension.
32
33    ARB_texture_multisample is required.
34
35    This extension interacts with NV_explicit_multisample.
36
37    This extension interacts with NV_framebuffer_multisample_coverage.
38
39    This extension interacts with EXT_direct_state_access.
40
41Overview
42
43    This specification extends NV_gpu_program4 to support per-sample fetching
44    from multisample textures described in ARB_texture_multisample.
45    Specifically, it adds:
46
47      * The TXFMS sample fetch instruction.
48
49      * Texture targets corresponding to the multisample textures added by
50        ARB_texture_multisample.
51
52      * A program option to enable these features.
53      
54    This specification also extends the ARB_texture_multisample extension
55    by adding support for EXT_direct_state_access and VCAA multisample
56    coverage with seperate <colorSamples> and <coverageSamples> parameters.
57
58New Procedures and Functions
59
60    void TexImage2DMultisampleCoverageNV(enum target,
61                                         sizei coverageSamples, sizei colorSamples,
62                                         int internalFormat,
63                                         sizei width, sizei height,
64                                         boolean fixedSampleLocations);
65                                         
66    void TexImage3DMultisampleCoverageNV(enum target,
67                                         sizei coverageSamples, sizei colorSamples,
68                                         int internalFormat,
69                                         sizei width, sizei height, sizei depth,
70                                         boolean fixedSampleLocations);
71                                         
72    void TextureImage2DMultisampleNV(uint texture, enum target,
73                                     sizei samples, int internalFormat,
74                                     sizei width, sizei height,
75                                     boolean fixedSampleLocations);
76                                     
77    void TextureImage3DMultisampleNV(uint texture, enum target,
78                                     sizei samples, int internalFormat,
79                                     sizei width, sizei height, sizei depth,
80                                     boolean fixedSampleLocations);
81                                     
82    void TextureImage2DMultisampleCoverageNV(uint texture, enum target,
83                                             sizei coverageSamples, sizei colorSamples,
84                                             int internalFormat,
85                                             sizei width, sizei height,
86                                             boolean fixedSampleLocations);
87                                             
88    void TextureImage3DMultisampleCoverageNV(uint texture, enum target,
89                                             sizei coverageSamples, sizei colorSamples,
90                                             int internalFormat,
91                                             sizei width, sizei height, sizei depth,
92                                             boolean fixedSampleLocations);
93
94New Tokens
95
96    Accepted by the <pname> parameter of GetTexLevelParameter:
97
98        TEXTURE_COVERAGE_SAMPLES_NV              0x9045
99        TEXTURE_COLOR_SAMPLES_NV                 0x9046
100
101Additions to Chapter 2 of the OpenGL 3.1 Specification (OpenGL Operation)
102
103    Modify Section 2.X.2, Program Grammar
104
105    If a program specifies the NV_texture_multisample program option, add to
106    existing grammar rules if not already present:
107
108    <texTarget>             ::= "2DMS"
109                              | "ARRAY2DMS"
110
111    <TEXop>                 ::= "TXFMS"
112
113    Add to section 2.X.4.4, Program Texture Access
114
115    Add row to table X.17
116
117                                                           coordinates used
118      texTarget          Texture Type                     s t r  layer  shadow
119      ----------------   ---------------------            -----  -----  ------
120      2DMS               TEXTURE_2D_MULTISAMPLE             <not supported>
121      ARRAY2DMS          TEXTURE_2D_MULTISAMPLE_ARRAY       <not supported>
122
123    Add row to table X.18
124
125                                      coordinates used
126      texTarget          supported      i j k  layer  lod
127      ----------------   ---------      -----  -----  ---
128      2DMS                  no          - - -    -     -
129      ARRAY2DMS             no          - - -    -     -
130
131    Replace or add language explaining TexelFetchMultisample after the
132    discussion of TexelFetch
133
134    The TXFMS instruction provides the ability to extract a single sample from
135    a specified renderbuffer, two-dimensional multisample, or two-dimensional
136    multisample array texture image using the function:
137
138      result_t_vec TexelFetchMultisample(int_vec coord, int_vec offset);
139
140    The extracted texel is converted to an (R,G,B,A) vector according to Table
141    3.20.  The result vector is interpreted as floating-point, signed integer,
142    or unsigned integer, according to the data type modifier of the
143    instruction.  If the internal format of the texture is not compatible with
144    the instruction's data type modifier, the extracted texel value is
145    undefined.
146
147    <coord> is a four-component signed integer vector used to identify the
148    single sample accessed. For the 2DMS and RENDERBUFFER targets, the x and y
149    components are used to select the pixel and the w component is used to
150    select the sample. For the ARRAY2DMS target, the x, y, and z components are
151    used to select the texel and the w component is used to select the sample.
152    All of the restrictions of TexelFetch apply to TexelFetchMultisample, with
153    the additional requirement that it must be called on a RENDERBUFFER, 2DMS,
154    or ARRAY2DMS texture target. If the sample number is greater than or equal
155    to the value of SAMPLES for the multisample texture, the results are
156    undefined.
157
158Additions to Chapter 3 of the OpenGL 3.1 Specification (Rasterization)
159
160    Add to the end of Section 3.8.4 (Multisample Textures):
161    
162    The commands
163    
164        void TexImage2DMultisampleCoverageNV(enum target,
165                                         sizei coverageSamples, sizei colorSamples,
166                                         int internalFormat,
167                                         sizei width, sizei height,
168                                         boolean fixedSampleLocations);
169                                         
170        void TexImage3DMultisampleCoverageNV(enum target,
171                                         sizei coverageSamples, sizei colorSamples,
172                                         int internalFormat,
173                                         sizei width, sizei height, sizei depth,
174                                         boolean fixedSampleLocations);
175                                         
176    establish the data storage, format, dimensions, and number of samples of a
177    multisample texture's image where the number of <colorSamples> and
178    <coverageSamples> can be explicitly specified.
179    
180    If <coverageSamples> is zero, then TEXTURE_COVERAGE_SAMPLES_NV 
181    is set to zero.  Otherwise <coverageSamples> represents a request 
182    for a desired minimum number of coverage samples. Since different 
183    implementations may support different coverage sample counts for 
184    multisampled rendering, the actual number of coverage samples 
185    allocated for the renderbuffer image is implementation dependent.  
186    However, the resulting value for TEXTURE_COVERAGE_SAMPLES_NV is
187    guaranteed to be greater than or equal to <coverageSamples> and no 
188    more than the next larger coverage sample count supported by the 
189    implementation.
190
191    If <colorSamples> is zero then TEXTURE_COLOR_SAMPLES_NV is set
192    to zero.  Otherwise, <colorSamples> represents a request for a 
193    desired minimum number of colors samples.  Since different 
194    implementations may support different color sample counts for 
195    multisampled rendering, the actual number of color samples 
196    allocated for the renderbuffer image is implementation dependent.
197    Furthermore, a given implementation may support different color 
198    sample counts for each supported coverage sample count.  The
199    resulting value for TEXTURE_COLOR_SAMPLES_NV is determined
200    after resolving the value for TEXTURE_COVERAGE_SAMPLES_NV.
201    If the requested color sample count exceeds the maximum number of
202    color samples supported by the implementation given the value of
203    TEXTURE_COVERAGE_SAMPLES_NV, the implementation will set
204    TEXTURE_COLOR_SAMPLES_NV to the highest supported value.  
205    Otherwise, the resulting value for TEXTURE_COLOR_SAMPLES_NV is
206    guaranteed to be greater than or equal to <colorSamples> and no 
207    more than the next larger color sample count supported by the 
208    implementation given the value of TEXTURE_COVERAGE_SAMPLES_NV.
209
210    If <colorSamples> is greater than <coverageSamples>, the error
211    INVALID_VALUE is generated.
212
213    If <coverageSamples> or <colorSamples> is greater than 
214    MAX_SAMPLES_EXT, the error INVALID_VALUE is generated.
215
216    If <coverageSamples> is greater than zero, and <colorSamples> is
217    zero, RENDERBUFFER_COLOR_SAMPLES_NV is set to an implementation
218    dependent value based on RENDERBUFFER_COVERAGE_SAMPLES_NV.
219    
220    An implementation may only support a subset of the possible
221    combinations of coverage samples and color samples.  Requests for
222    combinations not supported by the implementation are resolved to
223    a supported combination using the rules above.  The number of 
224    supported combinations is MAX_MULTISAMPLE_COVERAGE_MODES_NV.
225    MULTISAMPLE_COVERAGE_MODES_NV is an array of 
226    MAX_MULTISAMPLE_COVERAGE_MODES_NV pairs of integers representing
227    the combinations of coverage samples and color samples supported
228    by the implementation.  The first integer in each pair corresponds
229    to coverage samples, while the second corresponds to color samples.
230    
231    (Note: MULTISAMPLE_COVERAGE_MODES_NV and MAX_MULTISAMPLE_COVERAGE_MODES_NV
232    are specified in the NV_framebuffer_multisample_coverage extension.)
233
234    Add to the end of section 3.8.14 (Texture Objects):
235        
236    The following multisample texture update commands:
237    
238        void TextureImage2DMultisampleNV(uint texture, enum target,
239                                     sizei samples, int internalFormat,
240                                     sizei width, sizei height,
241                                     boolean fixedSampleLocations);
242                                         
243        void TextureImage3DMultisampleNV(uint texture, enum target,
244                                     sizei samples, int internalFormat,
245                                     sizei width, sizei height, sizei depth,
246                                     boolean fixedSampleLocations);
247                                         
248        void TextureImage2DMultisampleCoverageNV(uint texture, enum target,
249                                             sizei coverageSamples, sizei colorSamples,
250                                             int internalFormat,
251                                             sizei width, sizei height,
252                                             boolean fixedSampleLocations);
253                                                 
254        void TextureImage3DMultisampleCoverageNV(uint texture, enum target,
255                                             sizei coverageSamples, sizei colorSamples,
256                                             int internalFormat,
257                                             sizei width, sizei height, sizei depth,
258                                             boolean fixedSampleLocations);        
259
260    operate identically to the corresponding command where "Texture"
261    is substituted for "Tex" (and extension suffixes are dropped or
262    updated appropriately) except, rather than updating the current bound
263    texture for the texture unit indicated by the current active texture
264    state and the target parameter, these "Texture" commands update the
265    texture object named by the initial texture parameter.  If the
266    texture parameter is zero, then the target parameter selects the
267    default texture of the specified target to update.  The remaining
268    parameters following the initial texture parameter for the listed
269    "Texture" commands match the parameters for the corresponding "Tex"
270    command and are interpreted as they are for the "Tex" command.
271    If the texture parameter is for an unused name, the name becomes
272    used and the named texture object is set to a new state vector,
273    comprising all the state values listed in section 3.8.11, set
274    to the same initial values prior to the command's state update.
275    If the texture parameter is for a used name and that named texture
276    object has a different target than the specified target parameter,
277    the INVALID_OPERATION error is generated.  One consequence of this
278    error for commands that accepts TEXTURE_PROXY_* as a valid target
279    parameter is TEXTURE_PROXY_* target tokens generate errors if used
280    with a non-zero texture parameter because the target of a non-default
281    (non-zero) texture object is never a proxy target."
282
283Additions to Chapter 4 of the OpenGL 3.1 Specification (Per-Fragment Operations
284and the Frame Buffer)
285
286    None.
287
288Additions to Chapter 5 of the OpenGL 3.1 Specification (Special Functions)
289
290    None.
291
292Additions to Chapter 6 of the OpenGL 3.1 Specification (State and
293State Requests)
294
295    None.
296
297Additions to the AGL/GLX/WGL Specifications
298
299    None.
300    
301New State
302
303    (add to table 6.14, Textures (state per texture image p. 252)
304                                                                           Initial
305    Get Value                         Type  Get Command                    Value    Description          Section
306    --------------------------------  ----  -----------------------------  -------  -------------------  ------------
307    TEXTURE_COVERAGE_SAMPLES_NV        Z+   GetTexLevelParameter              0     Number of coverage   3.8.4
308                                                                                    samples per texel
309    TEXTURE_COLOR_SAMPLES_NV           Z+   GetTexLevelParameter              0     Number of color      3.8.4
310                                                                                    samples per texel
311
312Interactions with NV_explicit_multisample
313
314    If NV_explicit_multisample is not present, the language following the discussion
315    of Texelfetch in section 2.X.4.4, Program Texture Access will be new and should
316    omit any mention of sampling from renderbuffers.
317    
318Dependencies on EXT_direct_state_access
319
320    If EXT_direct_state_access is not supported, remove references to the
321    TextureImage* commands added by this extension.
322    
323Issues
324
325    (1) What should this extension be called?
326
327    RESOLVED: NV_texture_multisample. It contains the NVIDIA specific portions
328    of ARB_texture_multisample.
329
330    (2) What should the multisample texel fetch opcode be called?
331
332    RESOLVED: TEXFMS. It is currently called TXFMS to correspond to the GLSL
333    builtin, TexelFetchMultisample. It has been suggested that this builtin be
334    renamed. Even if it is, TEXFMS matches the opcode added via
335    NV_explicit_multisample. It is better to mismatch GLSL than have two opcodes
336    for the same operation.
337
338Revision History
339
340    Rev.    Date    Author    Changes
341    ----  --------  --------  -----------------------------------------
342    1     6/23/09   groth     Extracted from portions of an earlier version of
343                              ARB_texture_multisample 
344
345    2     9/10/09   pdaniell  Add support for VCAA and DSA
346