Name ARB_fragment_program_shadow Name Strings GL_ARB_fragment_program_shadow Contributors Pat Brown Benj Lipchak Eric Werness and contributors to the ARB_vertex_program and ARB_fragment_program working groups, the products of which provided the basis for this spec. Contact Bill Licea-Kane, AMD (bill.licea-kane 'at' amd.com) Notice Copyright (c) 2003-2013 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 IP Status Unknown, but Microsoft claims to own intellectual property related to ARB_fragment_program. This extension is an extension to ARB_fragment_program. Status Complete. Approved by ARB on December 16, 2003 Version Last Modified Date: November 4, 2006 Revision: 6 Number ARB Extension #36 Dependencies The extension is written against the OpenGL 1.3 Specification. ARB_fragment_program is required. ARB_shadow is required. EXT_texture_rectange affects the definition of this extension. Overview This extension extends ARB_fragment_program to remove the interaction with ARB_shadow. This extension defines the program option "ARB_fragment_program_shadow". If a fragment program specifies the option "ARB_fragment_program_shadow" SHADOW1D, SHADOW2D, SHADOWRECT are added as texture targets. When shadow map comparisons are desired, specify the SHADOW1D, SHADOW2D, or SHADOWRECT texture targets in texture instructions. Programs must assure that the comparison mode for each depth texture (TEXTURE_COMPARE_MODE) and/or the internal texture format (DEPTH_COMPONENT) and the targets of the texture lookup instructions match. Otherwise, if the comparison mode and/or the internal texture format are inconsistent with the texture target, the results of the texture lookup are undefined. Issues (1) What should this extension be called? RESOLVED: ARB_fragment_program_shadow. Shadow support is the only new feature. The name ARB_fragment_program2 should be used for a far more major revision to ARB_fragment_program. ARB_fragment_program1_1 is less descriptive. (2) Should this extension use the header string "!!ARBfp1.1" or a program option "ARB_fragment_program_shadow"? RESOLVED: Program option "ARB_fragment_program_shadow". (3) What form should the ARB_fragment_program_shadow option take? a. New sampler instructions. SHX result.color.a, fragment.texcoord[1], texture[0], 2D; b. New texture modifiers. TEX result.color.a, fragment.texcoord[1], texture[0], 2D,SHADOW; c. New texture targets. TEX result.color.a, fragment.texcoord[1], texture[0], SHADOW2D; d. New sampler instructions AND new texture modifiers. SHX result.color.a, fragment.texcoord[1], texture[0], 2D,SHADOW; e. New sampler instructions AND new texture targets. SHX result.color.a, fragment.texcoord[1], texture[0], SHADOW2D; RESOLVED: Choose the simplest option c, add new texture targets. All of the above forms are functionally equivalent. An earlier draft proposed option a, adding six new shadow instructions. The required shadow instructions are three variants of shadow instruction (non-projective, projective, and biased), and the same instructions with the modifier _SAT. Option b adds texture modifiers but requires additional semantic restrictions. Option c adds texture targets only. It is a sufficient and simple change to one grammar rule. Option d and e are listed for completeness. They require additional instructions and additional semantic restrictions. Note that option e is most similar to the resolution of this issue by ARB_fragment_shader and the OpenGL Shading Language. The OpenGL Shading Language has both built-in texture and shadow functions and sampler types, analogous to texture instructions and texture targets. The resolution here drops the added reduntancy and potential error checking in favor of simplicity, but is otherwise consistent. This resolution is also consistent with the precident already established in ARB_fragment_program, since we have a TEX instruction, not a TEX1D, TEX2D, TEXCUBE, TEX3D, TEXRECT instructions. (4) How should ARB_fragment_program_shadow function? a. Simply remove the interaction with ARB_shadow so that TEXTURE_COMPARE_MODE behaves exactly as specified in the OpenGL 1.4 specification. b. Add "SHADOW" targets to texture lookup instructions. TEXTURE_COMPARE_MODE is ignored. For samples from a SHADOW target TEXTURE_COMPARE_MODE is treated as COMPARE_R_TO_TEXTURE; otherwise, it is treated as NONE. c. Like (b), but with undefined results if TEXTURE_COMPARE_MODE and/or the internal format of the texture does not match the target. d. A hybrid of (a) and (b), where the SHADOW target means to use the TEXTURE_COMPARE_MODE state. RESOLVED - Option c, undefined behavior when the target and mode do not match. Program text is not simply loaded, it is compiled, optimized and then loaded. Options a and d would remove information from the optimizer. Which components of the texture coordinate are required for the sample? Specifically, is the r component of the texture coordinate required? Options b and c are both sufficient and retain the information required by optimizers. Option c is consistent with the resolution chosen by ARB_fragment_shader. (5) What if additional texture compare modes are added by future extensions to ARB_SHADOW? We do not anticipate future extensions adding additional texture compare modes. Only the additional mode COMPARE_T_TO_TEXTURE has even marginal utility, and then only for SHADOW1D targets. However, a future extension adding additional texture compare modes is not precluded. The language in this specification is carefully, if somewhat awkwardly, written to say the TEXTURE_COMPARE_MODE either "is NONE" or "is not NONE. (6) Does EXT_shadow_funcs interact with this extension? RESOLVED: It doesn't. ARB_shadow supports LEQUAL or GEQUAL comparison functions. EXT_shadow_funcs simply adds the additional functions LESS, GREATER, EQUAL, NOTEQUAL, ALWAYS, and NEVER. Whichever function is specified will be used for the comparison function. (7) Does ARB_shadow_ambient interact with this extension? RESOLVED: It doesn't. ARB_shadow returns a result in the range [0,1]. ARB_shadow_ambient simply maps this range to [TEXTURE_COMPARE_FAIL_ARB, 1]. The result will be returned in the specified range. (8) How would an existing fragment program be ported to use the program option ARB_fragment_program_shadow? RESOLVED: Fairly simply, but with a caveat on undefined behavior. !!ARBfp1.0 # A simple example of shadow map (R <= Dt) # # SHOULD make sure that the 2D texture bound to texture unit 0: # texture format of DEPTH_COMPONENT (for highest quality comparison) # TEXTURE_MAG_FILTER is NEAREST # TEXTURE_MIN_FILTER is NEAREST or NEAREST_MIPMAP_NEAREST # Assumes DEPTH_TEXTURE_MODE is LUMINANCE or INTENSITY # TEMP Result; ALIAS Dt = Result; TEX Dt, fragment.texcoord[0], texture[0], 2D; SGE Result, Dt.x, fragment.texcoord[0].z; # R <= Dt !!ARBfp1.0 OPTION ARB_fragment_program_shadow; # A simple example of shadow map (R<= Dt) # # MUST make sure that the 2D texture bound to texture unit 0: # texture format of DEPTH_COMPONENT and a # TEXTURE_COMPARE_MODE of COMPARE_R_TO_TEXTURE # Otherwise, the Result is undefined. # # Remember also that to get R <= Dt to set: # TEXTURE_COMPARE_FUNC of LEQUAL # # A single compare equivalent to the above example will result if: # TEXTURE_MAG_FILTER is NEAREST # TEXTURE_MIN_FILTER is NEAREST or NEAREST_MIPMAP_NEAREST # Otherwise, percent closer filtering may be applied. # TEMP Result; TEX Result, fragment.texcoord[0], texture[0], SHADOW2D; New Procedures and Functions None New Tokens None Additions to Chapter 2 of the OpenGL 1.3 Specification (OpenGL Operation) None Additions to Chapter 3 of the OpenGL 1.3 Specification (Rasterization) Modify Section 3.11.2 Fragment Program Grammar and Semantic Restrictions Replace grammar rule with ::= "1D" | "2D" | "3D" | "CUBE" | "RECT" | (if program option is present) ::= "SHADOW1D" | "SHADOW2D" | "SHADOWRECT" Add Section 3.11.4.5.3 Fragment Program Shadow Option If a fragment program specifies the "ARB_fragment_program_shadow" program option, the rule is modified to add the texture targets SHADOW1D, SHADOW2D and SHADOWRECT (See Section 3.11.2). Modify Section 3.11.6 Fragment Program Texture Instruction Set (replace 1st through 4th paragraphs with the following paragraphs) The first three texture instructions described below specify the mapping of 4-tuple input vectors to 4-tuple output vectors. The sampling of the texture works as described in section 3.8, except that texture environments and texture functions are not applicable, and the texture enables hierarchy is replaced by explicit references to the desired texture target (i.e., 1D, 2D, 3D, cube map, rectangle). These texture instructions specify how the 4-tuple is mapped into the coordinates used for sampling. The following function is used to describe the texture sampling in the descriptions below: vec4 TextureSample(float s, float t, float r, float lodBias, int texImageUnit, enum texTarget); Note that not all three texture coordinates, s, t, and r, are used by all texture targets. In particular, 1D texture targets only use the s component. 2D and RECT (non-power-of-two) texture targets only use the s and t components. SHADOW1D texture targets only use the s and r components. The descriptions of the texture instructions below supply all three components, as would be the case with CUBE, 3D, SHADOW2D, and SHADOWRECT targets. If a fragment program samples from a texture target on a texture image unit where the bound texture object is not complete, as defined in section 3.8.9, the result will be the vector (R, G, B, A) = (0, 0, 0, 1). If a fragment program does not specify the "ARB_fragment_program_shadow" program option, and if a fragment program samples from a texture target of 1D, 2D, or RECT, it is as if TEXTURE_COMPARE_MODE_ARB is NONE. If a fragment program specifies the "ARB_fragment_program_shadow" program option, the result returned of a sample from a texture target on a texture image unit is undefined if: the texture target is 1D, 2D, or RECT, and the texture object's internal format is DEPTH_COMPONENT_ARB, and the TEXTURE_COMPARE_MODE_ARB is not NONE; or the texture target is SHADOW1D, SHADOW2D, SHADOWRECT, and the texture object's internal format is DEPTH_COMPONENT_ARB, and the TEXTURE_COMPARE_MODE_ARB is NONE; or the texture target is SHADOW1D, SHADOW2D, SHADOWRECT, and the texture object's internal format is not DEPTH_COMPONENT_ARB. A fragment program will fail to load if it attempts to sample from multiple texture targets on the same texture image unit. For example, the following programs would fail to load: !!ARBfp1.0 TEX result.color.rgb, fragment.texcoord[0], texture[0], 2D; TEX result.color.a, fragment.texcoord[1], texture[0], 3D; END !!ARBfp1.0 OPTION ARB_fragment_program_shadow; TEX result.color.rgb, fragment.texcoord[0], texture[0], 2D; TEX result.color.a, fragment.texcoord[1], texture[0], SHADOW2D; END Additions to Chapter 4 of the OpenGL 1.3 Specification (Per-Fragment Operations and the Frame Buffer) None Additions to Chapter 5 of the OpenGL 1.3 Specification (Special Functions) None Additions to Chapter 6 of the OpenGL 1.3 Specification (State and State Requests) None Additions to Appendix A of the OpenGL 1.3 Specification (Invariance) None Additions to the AGL/GLX/WGL Specifications None Dependencies on EXT_texture_rectangle If EXT_texture_rectangle is not supported: Section 3.11.2 should be modified by removing the line: | "SHADOWRECT" from the grammar rule; and Section 3.11.6 should be modified by removing the discussion of the rectangle shadow texture target.