1Name 2 3 NV_internalformat_sample_query 4 5Name Strings 6 7 GL_NV_internalformat_sample_query 8 9Contact 10 11 Daniel Koch, NVIDIA (dkoch 'at' nvidia.com) 12 13Contributors 14 15 Piers Daniell, NVIDIA 16 Weiwan Liu, NVIDIA 17 18Status 19 20 Complete 21 22Version 23 24 Last Modified Date: October 10, 2014 25 Revision: 2 26 27Number 28 29 OpenGL Extension #475 30 OpenGL ES Extension #196 31 32Dependencies 33 34 This specification is written against the OpenGL 4.5 (Core Profile) 35 Specification (September 19, 2014). 36 37 OpenGL 4.2 or ARB_internalformat_query are required for an OpenGL 38 implementation. 39 40 OpenGL ES 3.0 is required for an OpenGL ES implementation. 41 42 This extension interacts with OpenGL ES 3.1. 43 44 This extension interacts with KHR_debug and OpenGL 4.3. 45 46 This extension interacts with OES_texture_storage_multisample_2d_array. 47 48Overview 49 50 Some OpenGL implementations support modes of multisampling which have 51 properties which are non-obvious to applications and/or which may not be 52 standards conformant. The idea of non-conformant AA modes is not new, 53 and is exposed in both GLX and EGL with config caveats and the 54 GLX_NON_CONFORMANT_CONFIG for GLX and EGL_NON_CONFORMANT_CONFIG for EGL, 55 or by querying the EGL_CONFORMANT attribute in newer versions of EGL. 56 57 Both of these mechanisms operate on a per-config basis, which works as 58 intended for window-based configs. However, with the advent of 59 application-created FBOs, it is now possible to do all the multisample 60 operations in an application-created FBO and never use a multisample 61 window. 62 63 This extension further extends the internalformat query mechanism 64 (first introduced by ARB_internalformat_query and extended in 65 ARB_internalformat_query2) and introduces a mechanism for a 66 implementation to report properties of formats that may also be 67 dependent on the number of samples. This includes information 68 such as whether the combination of format and samples should be 69 considered conformant. This enables an implementation to report 70 caveats which might apply to both window and FBO-based rendering 71 configurations. 72 73 Some NVIDIA drivers support multisample modes which are internally 74 implemented as a combination of multisampling and automatic 75 supersampling in order to obtain a higher level of anti-aliasing than 76 can be directly supported by hardware. This extension allows those 77 properties to be queried by an application with the MULTISAMPLES_NV, 78 SUPERSAMPLE_SCALE_X_NV and SUPERSAMPLE_SCALE_Y_NV properties. For 79 example, a 16xAA mode might be implemented by using 4 samples and 80 up-scaling by a factor of 2 in each of the x- and y-dimensions. 81 In this example, the driver might report MULTSAMPLES_NV of 4, 82 SUPERSAMPLE_SCALE_X_NV of 2, SUPERSAMPLE_SCALE_Y_NV of 2 and 83 CONFORMANT_NV of FALSE. 84 85 86New Procedures and Functions 87 88 void GetInternalformatSampleivNV(enum target, enum internalformat, 89 sizei samples, enum pname, 90 sizei bufSize, int *params); 91 92New Types 93 94 None. 95 96New Tokens 97 98 Accepted by the <target> parameter of GetInternalformatSampleivNV: 99 100 RENDERBUFFER 101 TEXTURE_2D_MULTISAMPLE 102 TEXTURE_2D_MULTISAMPLE_ARRAY 103 104 Accepted by the <pname> parameter of GetInternalformatSampleivNV: 105 106 MULTISAMPLES_NV 0x9371 107 SUPERSAMPLE_SCALE_X_NV 0x9372 108 SUPERSAMPLE_SCALE_Y_NV 0x9373 109 CONFORMANT_NV 0x9374 110 111 112Additions to Chapter 22 of the OpenGL 4.5 (Core Profile) Specification 113(Context State Queries) 114 115 Add a new section 22.3.ifsq "Internal Format Sample Queries": 116 117 Information about implementation-dependent support for sample related 118 properties of internal formats can be queried with the command 119 120 void GetInternalformatSampleivNV(enum target, enum internalformat, 121 sizei samples, enum pname, 122 sizei bufSize, int *params); 123 124 <internalformat> must be color-renderable, depth-renderable, or 125 stencil-renderable (as defined in section 9.4). 126 127 <target> indicates the usage of the <internalformat>, and must be one of 128 the targets that can be used for multisample resources, that is one of 129 RENDERBUFFER, TEXTURE_2D_MULTISAMPLE, or TEXTURE_2D_MULTISAMPLE_ARRAY. 130 131 <samples> indicates the number of samples of the <internalformat> for 132 which properties are being queried. It is an error if the requested 133 <samples> are not supported for requested <internalformat> and <target>. 134 GetInternalformativ with the SAMPLES property can be used to determine 135 if <samples> is supported. 136 137 No more than <bufSize> integers will be written into <params>. If 138 more data are available, they will be ignored and no error will be 139 generated. 140 141 <pname> indicates the information to query, and it is one of the 142 following values. When a known property is queried, the associated 143 value is written into <params>, otherwise <params> is unmodified. 144 145 - MULTISAMPLES_NV: returns the number of multisamples used when a 146 resource of the requested type and the specified <samples> is created. 147 148 - SUPERSAMPLE_SCALE_X_NV: returns the super-sample scaling factor that 149 is used in the X-dimension when a resource of the requested type and 150 the specified <samples> is created. 151 152 - SUPERSAMPLE_SCALE_Y_NV: returns the super-sample scaling factor that 153 is used in the Y-dimension when a resource of the requested type and 154 the specified <samples> is created. 155 156 - CONFORMANT_NV: returns the conformance-compliance of a resource 157 created with the requested type and the specified <samples>. 158 TRUE is returned if the format/sample combination is supported in a 159 compliant manner. FALSE is returned if the requested format/sample 160 combination is not conformant. If this query reports 161 non-conformant status and the debug output functionality is enabled, 162 the GL will generate a debug output message describing the caveats. 163 The message has the source DEBUG_SOURCE_API, the type 164 DEBUG_TYPE_UNDEFINED_BEHAVIOR, and an implementation-dependent ID. 165 166 Errors: 167 The INVALID_ENUM error is generated if <target> is not one of 168 RENDERBUFFER, TEXTURE_2D_MULTISAMPLE, or TEXTURE_2D_MULTISAMPLE_ARRAY. 169 170 The INVALID_ENUM error is generated if <internalformat> is not 171 color-, depth-, or stencil-renderable. 172 173 The INVALID_ENUM error is generated if <pname> is not one of 174 MULTISAMPLES_NV, SUPERSAMPLE_SCALE_X_NV, SUPERSAMPLE_SCALE_Y_NV, or 175 CONFORMANT_NV. 176 177 The INVALID_VALUE error is generated if <bufSize> is negative. 178 179 The INVALID_OPERATION error is generated if a resource of the requested 180 type and samples is not supported by the implementation. 181 182Additions to the WGL/GLX/EGL Specification 183 184 None. 185 186Dependencies on OpenGL ES 3.1 187 188 If OpenGL ES 3.1 is not supported in an OpenGL ES implementation, 189 ignore references to TEXTURE_2D_MULTISAMPLE <target> and resources. 190 191Dependencies on OES_texture_storage_multisample_2d_array. 192 193 If OES_texture_storage_multisample_2d_array is not supported in an 194 OpenGL ES implementation, ignore references to 195 TEXTURE_2D_MULTISAMPLE_ARRAY. If the extension is supported, replace 196 references to TEXTURE_2D_MULTISAMPLE_ARRAY with references to 197 TEXTURE_2D_MULTISAMPLE_ARRAY_OES. 198 199Dependencies on KHR_debug 200 201 If KHR_debug or OpenGL 4.3 are not supported, ignore references to 202 debug output functionality. If KHR_debug is supported in an OpenGL ES 203 context, append the _KHR suffix onto associated types. 204 205New State 206 207 None. 208 209Sample Code 210 211 // Obtain supported sample count for a format: 212 GLint num_sample_counts = 0; 213 GLenum ifmt = GL_RGBA8; 214 GLenum target = GL_TEXTURE_2D_MULTISAMPLE; 215 glGetInternalformativ(target, ifmt, NUM_SAMPLE_COUNTS, 1, 216 &num_sample_counts); 217 218 // get the list of supported samples for this format 219 GLint samples[num_sample_counts]; 220 glGetInternalformativ(target, ifmt, SAMPLES, num_sample_counts, samples); 221 222 // loop over the supported formats and get per-sample properties 223 for (int i=0; i<num_sample_counts; i++) 224 { 225 GLint multisample; 226 GLint ss_scale_x, ss_scale_y; 227 GLint conformant; 228 glGetInternalformatSampleivNV(target, ifmt, samples[i], 229 GL_MULTISAMPLES_NV, 230 1, &multisample); 231 glGetInternalformatSampleivNV(target, ifmt, samples[i], 232 GL_SUPERSAMPLE_SCALE_X_NV, 233 1, &ss_scale_x); 234 glGetInternalformatSampleivNV(target, ifmt, samples[i], 235 GL_SUPERSAMPLE_SCALE_Y_NV, 236 1, &ss_scale_y); 237 glGetInternalformatSampleivNV(target, ifmt, samples[i], 238 GL_CONFORMANT_NV, 1, &conformant); 239 // do something with this information :-) 240 } 241 242 243Conformance Tests 244 245 TBD 246 247Issues 248 249 None yet! 250 251 252Revision History 253 254 Rev. Date Author Changes 255 ---- -------- -------- ----------------------------------------- 256 1 09/24/14 dkoch Initial version 257 2 10/10/14 weiwliu Assign value to new tokens 258