Name ARB_fragment_coord_conventions Name Strings GL_ARB_fragment_coord_conventions Contributors Jason Green, TransGaming Daniel Koch, TransGaming Gavriel State, TransGaming Ryan Gordon, Destineer Nicholas Vining, Destineer John Kessenich, Intel Contact Mark Kilgard, NVIDIA (mjk 'at' nvidia.com) Daniel Koch, TransGaming (daniel 'at' transgaming.com) Notice Copyright (c) 2009-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 Status Complete. Approved by the ARB on July 3, 2009. Version Last Modified Date: August 2, 2009 Version: 10 Number ARB Extension #63 Dependencies This extension is written against the OpenGL 3.1 Specification but can apply to prior specifications. This extension interacts with ARB_fragment_program. This extension interacts with ARB_fragment_shader. This extension interacts with NV_fragment_program. This extension interacts with NV_fragment_program_option. This extension interacts with NV_fragment_program2. This extension interacts with NV_fragment_program4. Overview This extension provides alternative conventions for the fragment coordinate XY location available for programmable fragment processing. The scope of this extension deals *only* with how the fragment coordinate XY location appears during programming fragment processing. Beyond the scope of this extension are coordinate conventions used for rasterization or transformation. In the case of the coordinate conventions for rasterization and transformation, some combination of the viewport, depth range, culling state, and projection matrix state can be reconfigured to adopt other arbitrary clip-space and window-space coordinate space conventions. Adopting other clip-space and window-space conventions involves adjusting existing OpenGL state. However it is non-trivial to massage an arbitrary fragment shader or program to adopt a different window-space coordinate system because such shaders are encoded in various textual representations. The dominant 2D and 3D rendering APIs make two basic choices of convention when locating fragments in window space. The two choices are: 1) Is the origin nearest the lower-left- or upper-left-most pixel of the window? 2) Is the (x,y) location of the pixel nearest the origin at (0,0) or (0.5,0.5)? OpenGL assumes a lower-left origin for window coordinates and assumes pixel centers are located at half-pixel coordinates. This means the XY location (0.5,0.5) corresponds to the lower-left-most pixel in a window. Other window coordinate conventions exist for other rendering APIs. X11, GDI, and Direct3D version through DirectX 9 assume an upper-left window origin and locate pixel centers at integer XY values. By this alternative convention, the XY location (0,0) corresponds to the upper-left-most pixel in a window. Direct3D for DirectX 10 assumes an upper-left origin (as do prior DirectX versions) yet assumes half-pixel coordinates (unlike prior DirectX versions). By the DirectX 10 convention, the XY location (0.5,0.5) corresponds to the upper-left-most pixel in a window. Fragment shaders can directly access the location of a given processed fragment in window space. We call this location the "fragment coordinate". This extension provides a means for fragment shaders written in GLSL or OpenGL assembly extensions to specify alternative conventions for determining the fragment coordinate value accessed during programmable fragment processing. The motivation for this extension is to provide an easy, efficient means for fragment shaders accessing a fragment's window-space location to adopt the fragment coordinate convention for which the shader was originally written. New Procedures and Functions None New Tokens None Additions to Chapter 2 of the OpenGL 3.1 Specification (OpenGL Operation) None Additions to Chapter 3 of the OpenGL 3.1 Specification (Rasterization) Modify Section 3.9.2, "Shader Execution" In subsection "Shader Inputs" replace the paragraph beginning "The built-in variable gl_FragCoord ..." with: "The built-in variable gl_FragCoord holds the fragment coordinate (x_f,y_f,z_f,w_f) for the fragment. Computing the fragment coordinate depends on the fragment processing pixel-center and origin conventions (discussed below) as follows: { x_w - 0.5, if the fragment processing pixel-center x_f = { convention is integer { x_w, otherwise { H - y_w, if the fragment processing origin y_f' = { convention is upper-left { y_w, otherwise { y_f' - 0.5, if the fragment processing pixel-center y_f = { convention is integer { y_f', otherwise z_f = z_w w_f = 1 / w_c where (x_w, y_w, z_w) is the fragment's window-space position, w_c is the w component of the fragment's clip-space position, and H is the window's height in pixels. Note that the value of z_w already has a polygon offset added in, if enabled (see section 3.6.4). Also z_f must be precisely 0 or 1 in the case where z_w is either 0 or 1 respectively. The 1/w is computed from the w_c coordinate (see section 2.12), which is the result of the product of the projection matrix and the vertex's eye coordinates. Unless otherwise specified by layout qualifiers in the fragment shader (see section 4.3.x.1 "Input Layout Qualifier" of the OpenGL Shading Language Specification), the fragment processing pixel-center convention is half-integer and the fragment processing origin convention is lower-left." Additions to Chapter 4 of the OpenGL 3.1 Specification (Per-Fragment Operations and the Frame Buffer) None Additions to Chapter 5 of the OpenGL 3.1 Specification (Special Functions) None Additions to Chapter 6 of the OpenGL 3.1 Specification (State and State Requests) None Additions to the AGL/GLX/WGL Specifications None Additions to version 1.40.07 of the OpenGL Shading Language Specification "A new preprocessor #define is added to the OpenGL Shading Language: #define GL_ARB_fragment_coord_conventions 1 Including the following line in a shader can be used to control the language features described in this extension: #extension GL_ARB_fragment_coord_conventions : where is as specified in section 3.3." Additions to Chapter 4 of the OpenGL Shadering Language (Variables and Types) version 1.40.07 Add a new Section 4.3.x (Layout Qualifiers) as follows: "4.3.x Layout Qualifiers Layout qualifiers can appear with an individual variable declared with an interface qualifier: ; : layout( ) : comma separated list of : in out uniform Declarations of layouts can only be made at global scope, and only where indicated in the following subsection; their details are specific to what the interface qualifier is, and are discussed individually. The tokens in any are identifiers, not keywords. Generally they can be listed in any order. Order-dependent meanings exist only if explicitly called out below. Similarily, these identifiers are not case-sensitive, unless explicitly noted otherwise. 4.3.x.1 Input Layout Qualifiers Vertex shaders do not have any input layout qualifiers. Fragment shaders can have an input layout only for redeclaring the built-in variable gl_FragCoord (see section 7.2). The layout qualifier identifiers for gl_FragCoord are origin_upper_left pixel_center_integer By default, gl_FragCoord assumes a lower-left origin for window coordinates and assumes pixel centers are located at half-pixel coordinates. For example, the (x, y) location (0.5, 0.5) is returned for the lower-left-most pixel in a window. The origin can be changed by redeclaring gl_FragCoord with the identifier, moving the origin of gl_FragCoord to the upper left of the window, with y increasing in value toward the bottom of the window. The values returned can also be shifted by half a pixel in both x and y by the identifier so it appears the pixels are centered at whole number pixel offsets. This moves the (x, y) value returned by gl_FragCoord of (0.5, 0.5) by default, to (0.0, 0.0) with . Redeclarations are done as follows in vec4 gl_FragCoord; // redeclaration that changes nothing is allowed // All the following are allowed redeclarations that change behavior layout(origin_upper_left) in vec4 gl_FragCoord; layout(pixel_center_integer) in vec4 gl_FragCoord; layout(origin_upper_left, pixel_center_integer) in vec4 gl_FragCoord; If gl_FragCoord is redeclared in any fragment shader in a program, it must be redeclared in all the fragment shaders in that program that have a static use of gl_FragCoord. All redeclarations of gl_FragCoord in all fragment shaders in a single program must have the same set of qualifiers. Within any shader, the first redeclarations of gl_FragCoord must appear before any use of gl_FragCoord. The built-in gl_FragCoord is only predeclared in fragment shaders, so redeclaring it in any other shader language will be illegal. Redeclaring gl_FragCoord with and/or qualifiers only affects gl_FragCoord.x and gl_FragCoord.y. It has no affect on rasterization, transformation, or any other part of the OpenGL pipeline or language features." Dependencies on ARB_fragment_program extension 3.11.3.1 Fragment Attributes Modify this paragraph: "If a fragment attribute binding matches "fragment.position", the "x" and "y" components of the fragment attribute variable are filled with the (x,y) window coordinates of the fragment center, relative to the lower left corner of the window. The "z" component is filled with the fragment's z window coordinate. This z window coordinate undergoes an implied conversion to floating point. This conversion must leave the values 0 and 1 invariant. The "w" component is filled with the reciprocal of the fragment's clip w coordinate." to read: "If a fragment attribute binding matches "fragment.position", the "x", "y", "z", and "w" components of the fragment attribute variable are filled with the (f_x,f_y,f_z,f_w) components respectively of the fragment coordinate for the fragment." Add this section: "3.11.4.5.3 Fragment Coordinate Conventions Fragment Program Options These options affect the fragment coordinate conventions specified in the "Shader Inputs" subsection of section 3.11. If a fragment program specifies one of the option "ARB_fragment_coord_origin_upper_left", the fragment processing origin convention is upper-left (and otherwise is lower-left) for purposes of computing the fragment coordinate when the fragment program executes. If a fragment program specifies one of the option "ARB_fragment_coord_pixel_center_integer", the fragment processing pixel-center convention is integer (and otherwise is half-integer) for purposes of computing the fragment coordinate when the fragment program executes." Dependencies on NV_fragment_program extension When this extension is supported, modify the NV_fragment_program grammar to include: ::= "END" ::=