INCOMPLETE - DO NOT RELEASE IMPLEMENTATIONS OF THIS EXTENSION Name EXT_fragment_lighting Name Strings GL_EXT_fragment_lighting Version $Date: 1998/09/26 02:49:31 $ $Revision: 1.26 $ Number 102 Dependencies OpenGL 1.1 is required. SGIX_color_range affects the definition of this extension. Overview This extension adds a new lighting stage to the OpenGL pipeline. This stage occurs during fragment processing after the texture environment has been applied and before fog has been applied. The extension provides a mechanism for computing 'per-pixel lighting'. Fragment lighting applies to fragments generated by all primitives including pixel images. This extension doesn't eliminate vertex lighting, but can be used to complement it. For example, the diffuse contribution can be evaluated at each vertex, and the specular contribution can be evaluated at each fragment with the results being summed together to generate the final result. Ct Cf | |-------------------------------+ | | | ---------- | | | | | TexEnv | | | | | ---------- | | | ---------- | | Clamp | Nf Lf Hf Ff | ---------- | | | | | FragmentColorMaterial | ----------------- | | | | v Cf' | FragmentLight |<-o-<- Material {Am,Em,Dm,Sm,Nm,...} | | | | ----------------- | | | --------- | | Clamp | | --------- | Cl | | +---------------- v v ------------ | | | LightEnv | | | ------------ | --------- | Clamp | --------- | Cf'' | v ------- | | | Fog | | | ------- | v Patent Note To the extent that SGI has patent rights that are unavoidably infringed by all implementations of this extension, SGI will, upon request, grant a license under such patent rights to the requesting party subject to reasonable terms and conditions, and without incremental charge or fee. Such license shall be non-exclusive, and non-transferable, and shall be limited to implementations of the extension in combination with any conformance certified implementation of the OpenGL API. Such license is expressly contingent upon a grant back of a non-exclusive, royalty-free, perpetual, worldwide license to SGI and its OpenGL licensees under the requesting party's patent rights that are unavoidably infringed by all implementations of this extension or OpenGL. Issues * We specify a complete model and don't allow subsetting. if portions of the model aren't supported with hardware acceleration then a software implementation of the complete model is necessary. There should be sufficient mechanism for an implementation to include partial acceleration and easily identify when it can be used. The alternative is to allow subsetting and a mechanisms for enumerating the capability would this be any better? I don't think so. Lighting will be an important area of growth for OpenGL. I think we owe it to our developers to force a consistent growth direction by trying to look ahead a little. * We apply texture environment before lighting so that decals can be lighted correctly. The spec does not provide a mechanism for applying texture after lighting. There are applications where it would be useful to apply texture after lighting (e.g. shadows or spotlight effects), but we deliberately leave them out. Instead we will add binding posts in another extension to allow textures to be bound to the attenuation term, specular exponent, environment term, normal perturbation, etc. * Should the FragmentColorMaterial command really be done through texture binding posts and TexEnv moved after lighting? No. * New LightModel parameters? yes, NORMAL_INTERPOLATION control * We deliberately chose to decouple the control of normal interpolation for fragment lighting from ShadeModel, choosing to put it in the FragmentLightModel command. We chose not to provide any mechanism to allow flat coloring before vertex lighting, so FlatShading continues to mean that the vertex color after vertex lighting is used to provide a constant color across the face of a primitive. * Material parameters are not interpolated. If FragmentMaterial is enabled then the interpolated color parameter will be used as one or more of the material parameters, but there is no equivalent notion to per-vertex materials. If a material change occurs between a Begin/End sequence, then only the last material specified before the provoking vertex will affect the shading computation. * overload ColorMaterial & Material face param with FRAGMENT_FRONT, FRAGMENT_BACK, and FRAGMENT_FRONT_AND_BACK rather than separate commands? since the behaviour is somewhat different (not persistent) so it feels like it should be a different command * proxy mechanism for subsetting? proxy mechanism for determining what is supported in hardware. NO. * add some comments about where lighting parameters are sampled (fragment centers, pixel centers, ...) * shadow term is not quite right. removed it. * should the material be undefined after color material is disabled it should be well defined. fragment color material should be thought of as a switch which causes the material parameters to be sourced from the fragment material 'register' or from the fragment color. At all times queries to the fragment material refer to the material 'register' and whenever fragment color material is disabled, material parameters are sourced from the unperturbed fragment material 'register' * disallow fragment material changes between begin/end? seems okay, since we added a new command! - DONE * add a total number of lights so that implementations can share state between vertex and fragment lights yet be more flexible about whether the state is used for a vertex or fragment light (vimal). Yes. MAX_ACTIVE_LIGHTS_EXT * is the flatshading definition correct? unlike flatshading for vertex lighting, the color will not be constant, just the normal so N.L will vary across the face. Yes, it is what we want. There is now a mechanism which allows flat or smooth color with flat or smooth fragment lighting (flat or smooth normals). * treatment of alpha? alpha comes from the diffuse material if fragment lighting is enabled. * the state of FrontFace affects the interpretation of two-sided lighting. Should there be separate state for vertex and fragment lighting? No. its a property of the geometry and shouldn't different for the two light source types. New Procedures and Functions void FragmentLightModeliEXT(enum pname, int param); void FragmentLightModelfEXT(enum pname, float param); void FragmentLightModelivEXT(enum pname, int *params); void FragmentLightModelfvEXT(enum pname, float *params); void FragmentLightiEXT(enum light, enum pname, int param); void FragmentLightfEXT(enum light, enum pname, float param); void FragmentLightivEXT(enum light, enum pname, int *params); void FragmentLightfvEXT(enum light, enum pname, float *params); void GetFragmentLightivEXT(enum light, enum pname, int *params); void GetFragmentLightfvEXT(enum light, enum pname, float *params); void FragmentMaterialfEXT(enum face, enum pname, const float param); void FragmentMaterialiEXT(enum face, enum pname, const int param); void FragmentMaterialfvEXT(enum face, enum pname, const float *params); void FragmentMaterialivEXT(enum face, enum pname, const int *params); void FragmentColorMaterialEXT(enum face, enum mode); void GetFragmentMaterialfvEXT(enum face, enum pname, const float *params); void GetFragmentMaterialivEXT(enum face, enum pname, const int *params); void LightEnviEXT(enum pname, int param); New Tokens Accepted by the parameter of Enable, Disable, and IsEnabled, by the parameter of GetBooleanv, GetIntegerv, GetFloatv, and GetDoublev: FRAGMENT_LIGHTING_EXT 0x8400 FRAGMENT_COLOR_MATERIAL_EXT 0x8401 Accepted by the parameter of GetBooleanv, GetIntegerv, GetFloatv, and GetDoublev: FRAGMENT_COLOR_MATERIAL_FACE_EXT 0x8402 FRAGMENT_COLOR_MATERIAL_PARAMETER_EXT 0x8403 MAX_FRAGMENT_LIGHTS_EXT 0x8404 MAX_ACTIVE_LIGHTS_EXT 0x8405 CURRENT_RASTER_NORMAL_EXT 0x8406 Accepted by the parameter of LightEnviEXT, by the parameter of GetBooleanv, GetIntegerv, GetFloatv, and GetDoublev: LIGHT_ENV_MODE_EXT 0x8407 Accepted by the parameter of FragmentLightModeliEXT, FragmentLightModelfEXT, FragmentLightModelivEXT, FragmentLightModelfvEXT, GetBooleanv, GetIntegerv, GetFloatv, and GetDoublev: FRAGMENT_LIGHT_MODEL_LOCAL_VIEWER_EXT 0x8408 FRAGMENT_LIGHT_MODEL_TWO_SIDE_EXT 0x8409 FRAGMENT_LIGHT_MODEL_AMBIENT_EXT 0x840A FRAGMENT_LIGHT_MODEL_NORMAL_INTERPOLATION_EXT 0x840B Accepted by the parameter of FragmentLightfEXT, FragmentLightiEXT, FragmentLightfvEXT, and FragmentLightivEXT, and by the parameter of Enable, Disable, and IsEnabled, and by the parameter of GetFragmentLightfvEXT and GetFragmentLightivEXT: FRAGMENT_LIGHT0_EXT 0x840C . . . FRAGMENT_LIGHT7_EXT 0x8413 Additions to Chapter 2 of the 1.1 Specification (OpenGL Operation) Section 2.12 Current Raster Position ... The current raster position consists of three window coordinates xw, yw, and zw, a clip corrdinate wc value, an eye coordinate distance, a valid bit, and associated data consisting of a color, normal, and texture coordinates. It is set ... ... The current raster position requires five single-precision floating point values for its xw, yw, and zw window coordinates, its wc clip coordinate, and its eye coordinate distance, a single valid bit, a color (RGBA and color index), normal, and texture coordinates for associated data. In the initial state, the coordinates and texture coordinates are both (0,0,0,1), the eye coordinate distance is 0, the valid bit is set, the associated RGBA color is (1,1,1,1), the associated color index is 1, and the associated normal is (0,0,1). In RGBA mode, the associated color index always has its initial value; in color index mode, the RGBA color always maintains its initial value. Section 2.13 Colors and Coloring ... Next vertex lighting, if enabled produces a color. If vertex lighting is disabled, the current color is used in further processing. After vertex lighting, RGBA colors are clamped to the range [0,1]. A color index is converted to fixed-point and then its integer portion is masked (see section 2.13.16). After clamping or masking, a primitive may be flatshaded, indicating that all vertices of the primitive are to have the same color (and normal). Finally, a primitive is clipped, then colors (texture coordinates and normals) must be computed at the vertices introduced or modified by clipping. Additions to Chapter 3 of the 1.1 Specification (Rasterization) Section 3.6.3 Rasterization of Pixel Rectangles Conversion to Fragments ... A fragment arising from a group consisting of color data takes on the color index or color components of the group; the depth, normal and texture coordinates are taken from the current raster position's associated data. A fragment arising from a depth component takes the component's depth value; the color, normal, and texture coordinate are given by those associated with the current raster position. In both cases texture coordinates s, t, and r are preplaced with s/q, t/q, and r/q, respectively. If q is less than or equal to zero the results are undefined. Groups arising from DrawPixels with a of STENCIL_INDEX are treated specially and are described in section 4.3.1. Before Section 3.9 Fog insert: Section 3.9 Fragment Lighting If enabled, fragment lighting computes a color for each rasterized fragment by applying an equation defined by a client-specified lighting model to a collection of parameters that can include the fragment coordinates, the coordinates of one or more light sources, the fragment normal, and parameters defining the characteristics of the light source and current fragment material. Fragment lighting is only defined for RGBA mode, it has no effect in color index mode. Fragment lighting may be in one of two states: 1. Lighting Off. In this state the color assigned to a fragment is the rasterized fragment's post-texturing color. 2. Lighting On. In this state the color assigned to a fragment is the result of combining the rasterized fragment's post-texturing color and a color computed from the current fragment lighting parameters. The two colors are combined according to the function defined by Lighting Environment described below. Fragment lighting is turned either on or off using the generic Enable or Disable commands with the symbolic value FRAGMENT_LIGHTING_EXT. 3.9.1 Lighting Environment The command void LightEnviEXT(enum pname, int param); sets parameters of the lighting environment that specifies how the computed illumination value is combined with the post-texturing fragment color. is a symbolic constant indicating the parameter to be set, is a value to which to set a single valued parameter. The possible environment parameter is LIGHT_ENV_MODE_EXT. LIGHT_ENV_MODE_EXT may be set to one of REPLACE, MODULATE, or ADD. The value of LIGHT_ENV_MODE_EXT specifies an environment function. The result of this function depends on the post-texturing fragment color (Cf) and the color computed (Cl) in equation (3.2) below. The functions are specified in Table 3.3 REPLACE MODULATE ADD Rv = Rl Rv = RfRl Rv = Rf+Rl Gv = Gl Gv = GfGl Gv = Gf+Gl Bv = Bl Bv = BfBl Bv = Bf+Bl Av = Al Av = AfAl Av = Af+Al Table 3.3 Light environment functions 3.9.2 Lighting Operation The equation for the fragment illumination model is: C = Em emissive + Am*As ambient material*scene ambient color SUM{_i = 0 through Nf-1} { + Atten_i*SpotL_i*{ distance/spot light attenuation + Am*Al_i ambient material*ambient light + Dm*Dl_i*(N.L_i) diffuse material*diffuse light + Sm*Sl_i*(f_i)(N.H_i)^n specular material*specular light } } Nf is the number of fragment light sources N is the fragment normal vector L_i is the direction vector from the fragment position to the light source H_i is the half angle vector f_i is as defined in equation (2.2) n is the specular exponent (shininess) Rewrite the equation as: I[i] = Atten_i*SpotL_i*(Am*Al_i + Dm*Dl_i*(N.L_i) + Sm*Sl*(f_i)(N.H_i)^n) (3.1) and I' = SUM{i = 0 through Nf-1} I[i] C = Em + Am*As + I' (3.2) Equation (3.1) is the same as the vertex lighting equation described in section 2.13.1 for a single light source. Similar to vertex lighting, equation 3.2 is only evaluated for the R, G, and B components and the A component of C is determined from the alpha component of Dm. In order to compute the illumination terms for each fragment, the eye coordinates of the fragment can be used to compute the light direction, half angle vector, and attenuation factor in a manner similar to that used in the vertex lighting computations. It is permissible for an implementation to approximate these by computing these values as well as the normal vector at the vertices and interpolating and renormalizing the results. Fragment material state is maintained which is distinct from the vertex material state. The fragment material state consists of emission, ambient, diffuse, specular and shininess terms for both the front and back face of a primitive. Unlike vertex lighting, the fragment material state is constant across a primitive since it is resolved during rasterization. The results of the back face computation described in section 3.5.1 are used to determine whether the front material or back material is used when two sided lighting is enabled. There is separate state for each fragment light source. The fragment light source parameters are the same as the vertex light source parameters described in section 2.13.1. The minimum number of fragment light sources is 1. The number of available fragment light sources can be queried by issuing the Get command with the parameter set to MAX_FRAGMENT_LIGHTS_EXT. Distinct lighting model state is also maintained for vertex lighting and fragment lighting. The lighting model state is described in section 2.13.1. Fragment lighting model state includes one additional parameter, FRAGMENT_LIGHT_MODEL_NORMAL_INTERPOLATION_EXT, which controls how normals are selected for use in the fragment lighting computations for a primitive. If FLAT is selected for the lighting model, the normal from the provoking vertex (as described in Section 2.13.7 Flatshading) of the primitive for all fragment lighting computations for the primitive. If SMOOTH is specified a normal is computed for each fragment using the normals from all of the vertices of the primitive. Fragment lighting differs from vertex lighting in that all components of lighting parameters which are of type color in Table 2.7 are clamped to the range [0,1] when they are specified. Equation 3.1 is evaluated for each light source and the resulting colors are summed. This result is added to the material emissive and scene ambient terms as in equation 3.2 to produce the R, G, and B color components. The A component is determined from the diffuse material's A component. The resulting color components are clamped to the range [0,1] and then passed to the lighting environment computation. 3.9.3 Lighting Parameter Specification The fragment material state can be set with the commands FragmentMaterialfEXT, FragmentMaterialfvEXT, FragmentMaterialiEXT, FragmentMaterialivEXT using the values AMBIENT, DIFFUSE, SPECULAR, SHININESS and EMISSION. This state can be queried using the commands GetFragmentMaterialfvEXT and GetFragmentMaterialivEXT. Lighting parameters for fragment light i can be modified by issuing the commands FragmentLightfEXT, FragmentLightiEXT, FragmentLightfvEXT, and FragmentLightivEXT with the parameter set to FRAGMENT_LIGHTi_EXT. The lighting parameters for fragment light i can be queried by issuing the commands GetFragmentLightfvEXT and GetFragmentLightivEXT with the parameter set to FRAGMENT_LIGHTi_EXT. Lighting model parameters for fragment lighting can be modified using the commands FragmentLightModel{T}EXT, FragmentLightModel{T}vEXT. The lighting model parameters can be queried by issuing the Get command parameter set to the appropriate fragment lighting model parameter: FRAGMENT_LIGHT_MODEL_LOCAL_VIEWER_EXT, FRAGMENT_LIGHT_MODEL_TWO_SIDE_EXT, FRAGMENT_LIGHT_MODEL_AMBIENT_EXT or FRAGMENT_LIGHT_MODEL_NORMAL_INTERPOLATION_EXT. 3.9.4 FragmentColorMaterial One or more fragment material properties in Equation 3.2 can be replaced with the fragment's pre-texturing color, causing these color values to be used during the lighting computation. This behavior is enabled and disabled by calling Enable and Disable with the symbolic value FRAGMENT_COLOR_MATERIAL. The command that controls which of these modes is selected is void FragmentColorMaterial(enum face, enum mode); is one of FRONT, BACK, or FRONT_AND_BACK, indicating whether the front material, back material, or both are affected by the pre-texturing color. is one of EMISSION, AMBIENT, DIFFUSE, SPECULAR, or AMBIENT_AND_DIFFUSE and specifies which material property or properties are subsituted with the pre-texturing color. The substutions do not affect the material state. When FragmentColorMaterial is disabled the values in the fragment material state are used. GetFragmentMaterial returns the fragment material last specified with FragmentMaterial, regardless of whether FragmentColorMaterial is enabled. 3.9.5 Interactions with Vertex Lighting In order to allow implementions to share resources for vertex lighting and fragment lighting, an implementation may limit the maximum number of combined vertex and fragment lights to a number less than the sum of MAX_LIGHTS and MAX_FRAGMENT_LIGHTS_EXT. This limit can be queried using the Get command with parameter MAX_ACTIVE_LIGHTS_EXT. State for all fragment and vertex lights is always maintained. When multiple lights are enabled, priority is given to vertex lights starting with LIGHT0 through LIGHT where is equal to MAX_LIGHTS, followed by FRAGMENT_LIGHT0_EXT through FRAGMENT_LIGHT_EXT where is equal to MAX_FRAGMENT_LIGHTS_EXT. Additions to Chapter 4 of the 1.1 Specification (Per-Fragment Operations and the Frame Buffer) None Additions to Chapter 5 of the 1.1 Specification (Special Functions) None Additions to Chapter 6 of the 1.1 Specification (State and State Requests) TBD Additions to the GLX Specification TBD Dependencies on SGIX_color_range If SGIX_color_range is implemented, then the components of lighting parameters of type color, the result of evaluating the lighting equation and the results of evaluating the lighting environment are clamped to the extended color range rather than [0,1]. Errors INVALID_ENUM is generated if FragmentMaterial{T}EXT, FragmentMaterial{T}vEXT, or FragmentColorMaterialEXT, parameter is not FRONT, BACK or FRONT_AND_BACK. INVALID_ENUM is generated if FragmentMaterial{T}EXT or FragmentMaterial{T}vEXT parameter is not AMBIENT, DIFFUSE, SPECULAR, EMISSION, SHININESS, or AMBIENT_AND_DIFFUSE. INVALID_ENUM is generated if GetFragmentMaterial{T}vEXT parameter is not FRONT or BACK. INVALID_ENUM is generated if GetFragmentMaterial{T}vEXT parameter is not AMBIENT, DIFFUSE, SPECULAR, EMISSION, or SHININESS, INVALID_ENUM if FragmentColorMaterialEXT parameter is not EMISSION, AMBIENT, DIFFUSE, SPECULAR, or AMBIENT_AND_DIFFUSE INVALID_ENUM if LightEnviEXT parameter is not LIGHT_ENV_MODE_EXT or if parameter is not REPLACE, MODULATE, or ADD. INVALID_ENUM is generated if FragmentLightModel{T}EXT is not FRAGMENT_LIGHT_MODEL_LOCAL_VIEWER_EXT, FRAGMENT_LIGHT_MODEL_TWO_SIDE_EXT or FRAGMENT_LIGHT_MODEL_NORMAL_INTERPOLATION_EXT or if FragmentLightModel{T}vEXT, parameter is not FRAGMENT_LIGHT_MODEL_AMBIENT_EXT, FRAGMENT_LIGHT_MODEL_LOCAL_VIEWER_EXT FRAGMENT_LIGHT_MODEL_TWO_SIDE_EXT or FRAGMENT_LIGHT_MODEL_NORMAL_INTERPOLATION_EXT. INVALID_ENUM is generated if FragmentLight{T}EXT, FragmentLight{T}vEXT, or GetFragmentLight{T}vEXT parameter is not FRAGMENT_LIGHT0_EXT ... FRAGMENT_LIGHT_EXT where n is one minus the number of supported fragment lights, or if FragmentLight{T}EXT parameter is not SPOT_EXPONENT, SPOT_CUTOFF, CONSTANT_ATTENUATION, LINEAR_ATTENUATION, or QUADRATIC_ATTENUATION, or if FragmentLight{T}vEXT or GetFragmentLight{T}vEXT parameter is not AMBIENT, DIFFUSE, SPECULAR, POSITION, SPOT_DIRECTION, SPOT_EXPONENT, SPOT_CUTOFF, CONSTANT_ATTENUATION, LINEAR_ATTENUATION, or QUADRATIC_ATTENUATION. INVALID_VALUE is generated if FragmentLight{T}EXT or FragmentLight{T}vEXT parameter if a spot exponent value is specified outside the range [0,128], or if spot cutoff is specified outside the range [0,90] (except for the special value 180), or if a negative attenuation factor is specified. INVALID_OPERATION is generated if FragmentMaterial{T}EXT, FragmentMaterial{T}vEXT, FragmentColorMaterialEXT, GetFragmentMaterial{T}vEXT, LightEnviEXT, FragmentLight{T}EXT, FragmentLight{T}vEXT, FragmentLightModel{T}EXT, FragmentLightModel{T}vEXT or GetFragmentLight{T}vEXT is executed between execution of Begin and the corresponding execution of End. New State Get Value Get Command Type Initial Value Attribute --------- ----------- ---- ------------- --------- FRAGMENT_LIGHTING_EXT IsEnabled B False lighting/enable FRAGMENT_COLOR_MATERIAL_EXT IsEnabled B False lighting/enable FRAGMENT_COLOR_MATERIAL_PARAMETER_EXT GetIntegerv Z5 AMBIENT_AND_DIFFUSE lighting FRAGMENT_COLOR_MATERIAL_FACE_EXT GetIntegerv Z3 FRONT_AND_BACK lighting AMBIENT GetFragmentMaterialfvEXT 2xC (0.2,0.2,0.2,1.0) lighting DIFFUSE GetFragmentMaterialfvEXT 2xC (0.8,0.8,0.8,1.0) lighting SPECULAR GetFragmentMaterialfvEXT 2xC (0.0,0.0,0.0,1.0) lighting EMISSION GetFragmentMaterialfvEXT 2xC (0.0,0.0,0.0,1.0) lighting SHININESS GetFragmentMaterialfvEXT 2xR 0.0 lighting FRAGMENT_LIGHT_MODEL_AMBIENT_EXT GetFloatv C (0.2,0.2,0.2,0.2) lighting FRAGMENT_LIGHT_MODEL_LOCAL_VIEWER_EXT GetBooleanv B False lighting FRAGMENT_LIGHT_MODEL_TWO_SIDE_EXT GetBooleanv B False lighting FRAGMENT_LIGHT_MODEL_NORMAL_INTERPOLATION_EXT GetIntegerv Z2 SMOOTH lighting AMBIENT GetFragmentLightfvEXT 1*xC (0.0,0.0,0.0,1.0) lighting DIFFUSE GetFragmentLightfvEXT 1*xC see 3.x lighting SPECULAR GetFragmentLightfvEXT 1*xC see 3.x lighting POSITION GetFragmentLightfvEXT 1*xP (0.0,0.0,1.0,0.0) lighting CONSTANT_ATTENUATION GetFragmentLightfvEXT 1*xR 1.0 lighting LINEAR_ATTENUATION GetFragmentLightfvEXT 1*xR+ 0.0 lighting QUADRATIC_ATTENUATION GetFragmentLightfvEXT 1*xR+ 0.0 lighting SPOT_DIRECTION GetFragmentLightfvEXT 1*xD (0.0,0.0,-1.0) lighting SPOT_EXPONENT GetFragmentLightfvEXT 1*xR+ 0.0 lighting SPOT_CUTOFF GetFragmentLightfvEXT 1*xR+ 180.0 lighting FRAGMENT_LIGHTi_EXT IsEnabled 1*xB False lighting/enable LIGHT_ENV_MODE_EXT GetIntegerv Z3 REPLACE lighting CURRENT_RASTER_NORMAL_EXT GetFloatv N (0,0,1) current New Implementation Dependent State Get Value Get Command Type Minimum Value --------- ----------- ---- ------------- MAX_FRAGMENT_LIGHTS_EXT GetIntegerv Z+ 1 MAX_ACTIVE_LIGHTS_EXT GetIntegerv z+ MAX_LIGHTS