Name ARB_internalformat_query Name Strings GL_ARB_internalformat_query Contact Jan-Harald Fredriksen (jan-harald.fredriksen 'at' arm.com) Daniel Koch (daniel 'at' transgaming 'dot' com) Contributors Bruce Merry, ARM Daniel Koch, Transgaming Acorn Pooley, NVIDIA Christophe Riccio, Imagination Technologies Notice Copyright (c) 2011-2013 The Khronos Group Inc. Copyright terms at http://www.khronos.org/registry/speccopyright.html Status Complete. Approved by the ARB on 2011/06/20. Approved by the Khronos Promoters on 2011/07/29. Version Last Modified Date: June 13, 2011 Revision: 7 Number ARB Extension #112 Dependencies OpenGL 3.0 or ARB_framebuffer_object is required. This extension is written against the OpenGL 4.1 (Core Profile) Specification (July 25, 2010). ARB_texture_multisample affects the definition of this extension. Overview OpenGL 4.1 has a number of queries to indicate the maximum number of samples available for different formats. These give a coarse-grained query mechanism e.g. an implementation can expose different sample counts for integer and floating-point formats, but not for different floating-point formats. There is also no convenient way for the user to determine the granularity of sample counts available, only the maximum. This extension adds a query mechanism that allows the user to determine which sample counts are available for a specific internal format. IP Status No known IP claims. New Procedures and Functions void GetInternalformativ(enum target, enum internalformat, enum pname, sizei bufSize, int *params); New Types None. New Tokens Accepted by the parameter of GetInternalformativ: RENDERBUFFER TEXTURE_2D_MULTISAMPLE TEXTURE_2D_MULTISAMPLE_ARRAY Accepted by the parameter of GetInternalformativ: SAMPLES NUM_SAMPLE_COUNTS 0x9380 Additions to Chapter 2 of the OpenGL 4.1 (Core Profile) Specification (OpenGL Operation) None. Additions to Chapter 3 of the OpenGL 4.1 (Core Profile) Specification (Rasterization) In section 3.8.6 (Multisample Textures), replace the bulleted list of error conditions (for exceeding MAX_*_SAMPLES) and the preceeding sentence with: "The error INVALID_OPERATION will be generated if is greater than the maximum number of samples supported for this and , which can be determined by calling GetInternalformativ with a of SAMPLES (see section 6.X)." In the following paragraph, remove "or if samples is greater than MAX_SAMPLES". Additions to Chapter 4 of the OpenGL 4.1 (Core Profile) Specification (Per-Fragment Operations and the Frame Buffer) In section 4.4.2 (Attaching Images to Framebuffer Objects), under the description of RenderbufferStorageMultisample: Replace "If either or is greater than the value of MAX_RENDERBUFFER_SIZE, or if is greater than the value of MAX_SAMPLES, then the error INVALID_VALUE is generated. If is a signed or unsigned integer format and is greater than the value of MAX_INTEGER_SAMPLES, then the error INVALID_OPERATION is generated (see ``Required Renderbuffer Formats'' below)." with "If either or is greater than the value of MAX_RENDERBUFFER_SIZE then the error INVALID_VALUE is generated. If is greater than the maximum number of samples supported for then the error INVALID_OPERATION is generated (see GetInternalformativ in section 6.X)." Additions to Chapter 5 of the OpenGL 4.1 (Compatibility Profile) Specification (Special Functions) Add GetInternalformativ to the list of commands not included in display lists. Additions to Chapter 6 of the OpenGL 4.1 (Core Profile) Specification (State and State Requests) Add a new section 6.1.X "Internalformat queries" Information about implementation-dependent support for internal formats can be queried with the command void GetInternalformativ(enum target, enum internalformat, enum pname, sizei bufSize, int *params); must be color-renderable, depth-renderable or stencil-renderable (as defined in section 4.4.4). indicates the usage of the , and must be one of RENDERBUFFER, TEXTURE_2D_MULTISAMPLE, or TEXTURE_2D_MULTISAMPLE_ARRAY, corresponding to usage as a renderbuffer, 2D multisample texture, or 2D multisample array texture. No more than integers will be written into . If more data are available, they will be ignored and no error will be generated. indicates the information to query, and is one of the following: - SAMPLES: The sample counts supported for this and are written into , in descending order. Only positive values are returned. - NUM_SAMPLE_COUNTS: The number of sample counts that would be returned by querying SAMPLES is returned in . Note that querying SAMPLES with a of 1 will return just the maximum supported number of samples for this format. The maximum value in SAMPLES is guaranteed to be at least the lowest of the following: - The value of GetIntegerv(MAX_INTEGER_SAMPLES), if is a signed or unsigned integer format. - The value of GetIntegerv(MAX_DEPTH_TEXTURE_SAMPLES), if is a depth/stencil-renderable format and is TEXTURE_2D_MULTISAMPLE or TEXTURE_2D_MULTISAMPLE_ARRAY. - The value of GetIntegerv(MAX_COLOR_TEXTURE_SAMPLES), if is a color-renderable format and is TEXTURE_2D_MULTISAMPLE or TEXTURE_2D_MULTISAMPLE_ARRAY. - The value of GetIntegerv(MAX_SAMPLES). Additions to Appendix A of the OpenGL 4.1 (Core Profile) Specification (Invariance) None. Additions to Appendix D of the OpenGL 4.1 (Core Profile) Specification (Shared Objects and Multiple Contexts) None. GLX Protocol XXX - TODO. Dependencies on ARB_texture_multisample If OpenGL 3.2 or ARB_texture_multisample is not supported, then TEXTURE_2D_MULTISAMPLE and TEXTURE_2D_MULTISAMPLE_ARRAY are not supported parameters to GetInternalformativ. Dependencies on OpenGL ES If implemented on OpenGL ES (together with an extension adding RenderbufferStorageMultisample), then this extension behaves as specified, except: - Ignore all references to multisample textures and display lists. - Ignore all references to MAX_COLOR_TEXTURE_SAMPLES, MAX_DEPTH_TEXTURE_SAMPLES, MAX_INTEGER_SAMPLES and MAX_SAMPLES. Errors If the parameter to GetInternalformativ is not color-, depth- or stencil-renderable, then an INVALID_ENUM error is generated. If the parameter to GetInternalformativ is not one of TEXTURE_2D_MULTISAMPLE, TEXTURE_2D_MULTISAMPLE_ARRAY or RENDERBUFFER then an INVALID_ENUM error is generated. If the parameter to GetInternalformativ is not SAMPLES or NUM_SAMPLE_COUNTS, then an INVALID_ENUM error is generated. If the parameter to GetInternalformativ is negative, then an INVALID_VALUE error is generated. If the parameter to TexImage2DMultisample, TexImage3DMultisample or RenderbufferStorageMultisample is greater than the maximum number of samples supported for the target and internalformat, an INVALID_OPERATION error is generated. An INVALID_VALUE error is no longer generated if the argument to TexImage2DMultisample, TexImage3DMultisample or RenderbufferStorageMultisample is greater than the value of GetIntegerv(MAX_SAMPLES). New State None. New Implementation Dependent State Changes to table 6.52, p. 393 (Implementation Dependent Values) Minimum Get Value Type Get Command Value Description Sec. --------- ---- ----------- ------- ------------------------------------ ----- MAX_DEPTH_TEXTURE_SAMPLES Z+ GetIntegerv 1 Maximum number of samples supported 6.1.X for all depth/stencil formats in a multisample texture MAX_COLOR_TEXTURE_SAMPLES Z+ GetIntegerv 1 Maximum number of samples supported 6.1.X for all color formats in a multisample texture MAX_INTEGER_SAMPLES Z+ GetIntegerv 1 Maximum number of samples supported 6.1.X for all integer format multisample buffers (only the description and section numbers change) Changes to table 6.54, p. 395 (Framebuffer Dependent Values) Minimum Get Value Type Get Command Value Description Sec. --------- ---- ----------- ------- ------------------------------------ ----- MAX_SAMPLES Z+ GetIntegerv 4 Maximum number of samples supported 6.1.X for all non-integer formats (only the description and section number change - note this query should probably be in table 6.52 to start with) Add new table 6.X Internalformat-specific Implementation Dependent Values after 6.52 Minimum Get Value Type Get Command Value Description Sec. --------- ---- ----------- ------- ------------------------------------ ----- SAMPLES 0*xZ+ GetInternalformativ fn1 Supported sample counts 6.X NUM_SAMPLE_COUNTS Z+ GetInternalformativ 1 Number of supported sample counts 6.X fn1: see section 6.X. Sample Code To determine all the sample counts available for a specific renderbuffer format: GLint *samples; GLint samples_length, i; glGetInternalformativ(GL_RENDERBUFFER, format, GL_NUM_SAMPLE_COUNTS, 1, &samples_length); samples = malloc(samples_length * sizeof(GLint)); glGetInternalformativ(GL_RENDERBUFFER, format, GL_SAMPLES, samples_length, samples); for (i = 0; i < samples_length; i++) { printf("Format %#x supports %d samples\n", samples[i]); } To determine the maximum sample count available for a specific renderbuffer format: GLint max_samples; glGetInternalformativ(GL_RENDERBUFFER, format, GL_SAMPLES, 1, &max_samples); Conformance Tests 1. Test each of the error conditions described in Errors. 2. For each format that is not color-, depth- or stencil-renderable (if any), test that INVALID_ENUM is generated if passed to GetInternalformativ (e.g. LUMINANCE_ALPHA). 3. Call GetInternalformativ for each in turn with a of zero; check that is not modified and that no error results. 4. For each color-, depth- or stencil-renderable format and each target: 4.1. Query NUM_SAMPLE_COUNTS and verify that it is greater than zero. 4.2. Query SAMPLES, using a larger-than-necessary buffer, and check that only NUM_SAMPLE_COUNTS values are written. 4.3. Check that the values returned by SAMPLES are all positive and strictly decreasing. 4.4. Query MAX_SAMPLES and check that it matches the first value returned by SAMPLES. 4.5. Check that MAX_SAMPLES is at least the lower bound computed from MAX_SAMPLES, MAX_INTEGER_SAMPLES, MAX_COLOR_TEXTURE_SAMPLES and MAX_DEPTH_TEXTURE_SAMPLES. 4.6. Check that MAX_SAMPLE_MASK_WORDS is at least ceil(MAX_SAMPLES / 32). Issues 1) Should we have the MAX_SAMPLES query as well as the SAMPLES query? It's syntactic sugar (since you can just take the largest value in the SAMPLES array), but very convenient sugar since you don't have to allocate a dynamically-sized array. It also simplifies the specification. RESOLVED: no, we don't need it. Passing a of 1 when querying SAMPLES gives the same effect. 2) Should we explicitly include 0 in the list of sample counts (meaning "not multisampled")? It might allow one to indicate that certain formats are flat-out unsupported with certain targets but supported with others. RESOLVED: no, we would rather layer on a separate later. 3) For multisample textures, is a per-target query too fine-grained? Should the just be TEXTURE instead of TEXTURE_2D_MULTISAMPLE[_ARRAY]? RESOLVED: Keep the per-target query as it may useful to distinguish results for some future values of . 4) What should the new command be called? RESOLVED: GetInternalformativ GetInternalformativ is potentially confusing, but consistent with GL precedent such as GetQueryiv (which returns information such as the number of bits supported for a specific query target). 5) What should the query of the number of samples counts be called? RESOLVED: NUM_SAMPLE_COUNTS The original proposal was NUM_SAMPLES, which is consistent with NUM_COMPRESSED_TEXTURE_FORMATS. However, it's confusing because what is being queried is not the number of samples (whereas NUM_COMPRESSED_TEXTURE_FORMATS is the number of compressed texture formats). NUM_SAMPLE_COUNTS is also consistent with the NUM_COMPRESSED_TEXTURE_FORMATS precedent and the description of this value. Another proposal was SAMPLES_LENGTH, but this is misleading because in OpenGL LENGTH is only used for string length. 6) What should GetIntegerv(MAX_INTEGER_SAMPLES) and similar queries return (excluding MAX_SAMPLES - see next issue)? Discussion: there are (at least) two options: A. Querying MAX_INTEGER_SAMPLES returns a count that is guaranteed to be supported for all integer formats, but some integer formats may support more samples and the existing errors are relaxed to allow this. B. Require that all integer formats support the same maximum number of samples, and GetInternalformativ becomes an alternative interface to the same set of limits. RESOLVED: option A. 7) What should GetIntegerv(MAX_SAMPLES) return? In OpenGL 4.1, MAX_SAMPLES serves two purposes. A. An upper bound on the number of samples supported for any format. This manifests in INVALID_VALUE errors when trying to use more than this number. B. A number of samples that is guaranteed to be supported for all formats that don't fall into certain classes (such as integer formats). Backwards compatibility would suggest that it should return option B in future, although this leaves no way to determine the maximum number of samples supported for any format unless a new query is introduced. RESOLVED: option B. 8) Does this extension make the MAX_SAMPLES query unnecessary? RESOLVED: MAX_SAMPLES will need to be retained in API versions where it already exists (for backwards compatibilities), but there is no need to add it as this query provides more accurate information and it is expected that shipping hardware will support different numbers of samples for different formats. 9) Can we query additional properties supported for an internal format in addition to multisample-related information with this API? RESOLVED: DEFERRED. Yes this API is suitable for that, but the specification is left for a layered extension. Other possible include: MAX_WIDTH - maximum width of object MAX_HEIGHT - maximum height of object MAX_DEPTH - maximum depth/# of layers of object MAX_COMBINED_SIZE - maximum size of object (w*h*d) (due to implementation-specific limitations) FRAMEBUFFER_RENDERABLE - can be rendered to via FBO attachment FRAMEBUFFER_RENDERABLE_BLEND - can be rendered to via FBO attachment when blending is enabled MIPMAPS - more than one mipmap can be supported GENERATE_MIPMAPS - is generate mipmaps supported READPIXEL - framebuffers with this internal format can be read directly with an appropriate format/type by ReadPixels FILTER_LINEAR - can the MIN/MAG filter be set to LINEAR values? Are filters other than NEAREST supported? SRGB_READ - texture reads from this internalformat occur in SRGB colorspace SRGB_WRITE - framebuffers with this internalformat can be rendered to with FRAMEBUFFER_SRGB enabled SRGB_DECODE - textures of this format support toggling TEXTURE_SRGB_DECODE (ie EXT_texture_sRGB_decode) VERTEX_TEXTURE - textures with this internalformat can be sampled from vertex shaders TESS_CONTROL_TEXTURE - textures with this internalformat can be sampled from tessellation control shaders TESS_EVALUATION_TEXTURE - textures with this internalformat can be sampled from tessellation evaluation shaders GEOMETRY_TEXTURE - textures with this internalformat can be sampled from geometry shaders FRAGMENT_TEXTURE - textures with this internalformat can be sampled from fragment shaders TEXTURE_SHADOW - textures with this internalformat support shadow samplers TEXTURE_GATHER - textures with this internalformat support texture gather operations TEXTURE_GATHER_SHADOW - textures with this internalformat support texture gather operations with shadow samplers SHADER_IMAGE_LOAD - textures with this internalformat support image load operations from shaders SHADER_IMAGE_STORE - textures with this internalformat support image store operations from shaders SHADER_IMAGE_ATOMIC - textures with this internalformat support atomic memory operations from shaders FORMAT_SUPPORTED - the requested internal format is known and supported for at least some subset of the possible operations ACTUAL_INTERNALFORMAT - the actual internalformat used by the implementation when the specified internalformat is requested PERFORMANCE_HINT - an indication that this format will or may operate at reduced performance in some cases (should this be a bitfield, array, or a specific bit on each of the other queries?) Possible values for some of the above pnames: - HARDWARE (or SUPPORTED), SOFTWARE (or CAVEAT), UNSUPPORTED. Additional Values for that would be valid for TEXTURE_1D TEXTURE_1D_ARRAY TEXTURE_2D TEXTURE_2D_ARRAY TEXTURE_3D TEXTURE_CUBE_MAP TEXTURE_CUBE_MAP_ARRAY TEXTURE_RECTANGLE TEXTURE_BUFFER Could also consider meta targets such as: ALL ANY TEXTURE 10) Is the parameter required? If so, should it be the first or second parameter? RESOLVED: a) Yes. It is possible that in some implementations and for some of the possible uses of this query, that the results will depend on the texture target. b) First parameter. All other entry points that take a have it as the first parameter. Revision History Revision 7, 2011/06/13 dgkoch - recast as ARB extension Revision 6, 2011/05/19 dgkoch - resolved issue 3, 9 per F2F. Revision 5, 2011/05/16 dgkoch - resolved issue 10 per F2F. Keep target; as the first parameter. - fix extension name - updates to Issue 9 Revision 4, 2011/05/11 dgkoch - also fix the formal paramter in the New Functions area - updates to issue 9, added issue 10 Revision 3, 2011/05/05 dgkoch - rename the formal parameter from 'format' to 'internalformat' to match the spec body. - changed SAMPLES_LENGTH to NUM_SAMPLE_COUNTS - added issue 9 Revision 2, 2011/04/21 bmerry - Fix typo InternalFormat -> Internalformat - Removed per-format MAX_SAMPLES query - Marked issues 1, 2, and 4-7 as resolved Revision 1, 2011/04/13 bmerry - First draft.