1XXX - Incomplete 2 3Name 4 5 EXT_multiple_textures 6 7Name Strings 8 9 GL_EXT_multiple_textures 10 11Number 12 13 ??? 14 15Basic approach: 16 17Initially I started out adding enumerants and functions everywhere to 18add the concept of multiple current textures to the OpenGL API. This 19quickly became unwieldy because the number of functions affected is very 20large and the number of enumerants needed for texture control, queries, 21texgen, evaluators, vertex arrays, etc. soared into the hundreds. 22 23Rather than try to change a fundamental assumption of the API, I decided 24to keep the notion of a current texture but add a function to allow 25setting that current texture to any of a number of textures kept current 26in the implementation. The API changes are thus much smaller. The 27internal changes are still substantial but smaller than in the previous 28approach because of the lack of new parameters to verify and new 29functions to implement. 30 31New enumerants: 32 33GL_MAX_CURRENT_TEXTURES 34 35Specifies the maximum number of textures which may simultaneously be 36current. This number must be at least two and can be no more than 37sixteen. 38 39GL_CURRENT_TEXTURE_INDEX 40 41Retrieves the index of the current texture. 42 43GL_SUB 44GL_COMBINE_COLOR 45GL_TWICE_COMBINE_COLOR 46GL_TEX_COLOR 47GL_TWICE_TEX_COLOR 48GL_ONE_MINUS_COMBINE_COLOR 49GL_ONE_MINUS_TEX_COLOR 50GL_COMBINE_ALPHA 51GL_TWICE_COMBINE_ALPHA 52GL_COMBINE_ALPHA_REPLACES_COLOR 53GL_TEX_ALPHA 54GL_TWICE_TEX_ALPHA 55GL_TEX_ALPHA_REPLACES_COLOR 56GL_ONE_MINUS_COMBINE_ALPHA 57GL_ONE_MINUS_TEX_ALPHA 58 59Add operations allowed for texturing combining. 60 61GL_TEXCOMBINE_CLAMP 62 63Specifies whether intermediate results should be clamped during texture 64combining. This may result in higher or lower performance depending on 65the implementation. An application can check whether clamping is 66desirable or not by querying the following enumerant. 67 68GL_TEXCOMBINE_NATURAL_CLAMP 69 70Indicates whether the implementation prefers texcombine clamping or not. 71Querying this enumerant returns GL_TRUE, GL_FALSE or GL_DONTCARE, 72indicating that the implementation prefers clamping, does not prefer 73clamping or is unaffected by the clamping setting. 74 75The following enumerants are numbered consecutively from the 0 entry to 76the 15 entry, where n is replaced by the number of the particular 77instance. This restricts the possible set of current textures to 78sixteen simultaneously active textures. 79 80GL_TEXCOORDn_BIT 81 82Used to indicate the texture coordinate to affect. The legal range for 83n for a particular implementation is from 0 to 84GL_MAX_CURRENT_TEXTURES-1. 85 86GL_TEXCOMBINE_COMBINE_COLORn 87GL_TEXCOMBINE_COLOR_OPn 88GL_TEXCOMBINE_TEX_COLORn 89GL_TEXCOMBINE_COMBINE_ALPHAn 90GL_TEXCOMBINE_ALPHA_OPn 91GL_TEXCOMBINE_TEX_ALPHAn 92 93Used to query the current settings for texture combine functions. The 94legal range for n for a particular implementation is 0 to 95GL_MAX_CURRENT_TEXTURES-2. 96 97New functions: 98 99void glCurrentTextureIndex(GLuint index); 100 101Sets the current texture index. index must range from 0 to 102GL_MAX_CURRENT_TEXTURES-1 or GL_INVALID_VALUE is generated. The current 103texture index is used for every OpenGL API which references texture 104state without explicitly specifying a texture index. 105 106The default index is zero. The current index can be retrieved with 107glGet for GL_CURRENT_TEXTURE_INDEX. 108 109void glMultiTexCoord{1234}{sifd}{v}(GLbitfield mask, T coords); 110 111Sets the texture coordinate for all textures with a corresponding bit 112set in the given mask. mask is a bitfield made up of any combination of 113bits taken from the GL_TEXCOORDn_BIT values. Other parameters are as for 114glTexCoord. glMultiTexCoord(n, ...) can be replaced by the code 115sequence 116 glCurrentTextureIndex(n); 117 glTexCoord(...); 118for each bit n set in the mask. It is included for performance and 119programming convenience. 120 121There is no corresponding function for retrieval as queries are not 122expected to be common enough to warrant a special query enumerant. To 123query the n'th texture coordinate, set the texture index to n and do a 124glGet for GL_CURRENT_TEXTURE_COORDS. 125 126void glBindNthTexture(GLuint index, GLenum target, GLuint texture); 127 128Bind the given texture object to the n'th slot for the given target. 129Operates exactly as glBindTexture except for directly acting on the 130indexed texture instead of the current texture index. The current 131texture index is not changed. 132 133void glNthTexCombineFunc(GLuint index, GLenum combineColorFactor, GLenum 134colorOp, GLenum texColorFactor, GLenum combineAlphaFactor, GLenum 135alphaOp, GLenum texAlphaFactor); 136 137glNthTexCombineFunc is used to control how all of the currently enabled 138textures are combined together before being combined with the fragment. 139The n'th combine function controls how texture values at index n and n+1 140are combined, so there are m-1 combine functions for m enabled textures. 141index selects the function to be set while combineColorFactor, colorOp, 142texColorFactor, combineAlphaFactor, alphaOp and texAlphaFactor control 143how texture values are combined to produce the resulting texture value. 144 145When a fragment is being textured all current textures contribute to a 146final texture value which is combined with the fragment through the 147normal texture environment function. This texture value is initialized 148from the first enabled texture and then modified by following enabled 149textures using the texture combine functions. 150 151In the following equation: 152 Tc is the current combined texture color. 153 Ta is the current combined texture alpha. 154 texColor(n) is the n'th texture's color. 155 texAlpha(n) is the n'th texture's alpha. If the texture has no 156alpha the value is one. 157 158 n = 0 159 Tc = texColor(0), Ta = texAlpha(0). 160 161 n > 0 162 Tc = (Tc * combineColorFactor) colorOp 163(texColor(n) * texColorFactor). 164 Ta = (Ta * combineAlphaFactor) alphaOp 165(texAlpha(n) * texAlphaFactor). 166 167combineColorFactor and texColorFactor are one of GL_ZERO, GL_ONE, 168GL_COMBINE_COLOR, GL_TWICE_COMBINE_COLOR, GL_TEX_COLOR, 169GL_TWICE_TEX_COLOR, GL_COMBINE_ALPHA, GL_TWICE_COMBINE_ALPHA, 170GL_COMBINE_ALPHA_REPLACES_COLOR, GL_TEX_ALPHA, GL_TWICE_TEX_ALPHA, 171GL_TEX_ALPHA_REPLACES_COLOR, GL_ONE_MINUS_COMBINE_COLOR, 172GL_ONE_MINUS_TEX_COLOR, GL_ONE_MINUS_COMBINE_ALPHA and 173GL_ONE_MINUS_TEX_ALPHA. Most of these factors are self-explanatory. 174The ALPHA_REPLACES_COLOR enumerants replicate the requested alpha and 175replace the color rather than doing a multiply. This allows the alpha 176channel to contain a monochrome color for specular highlights or other 177effects. 178 179combineAlphaFactor and texAlphaFactor are one of GL_ZERO, GL_ONE, 180GL_COMBINE_ALPHA, GL_TWICE_COMBINE_ALPHA, GL_TEX_ALPHA, 181GL_TWICE_TEX_ALPHA, GL_ONE_MINUS_COMBINE_ALPHA and 182GL_ONE_MINUS_TEX_ALPHA. 183 184colorOp and alphaOp are one of GL_ADD or GL_SUB. 185 186If GL_TEXCOMBINE_CLAMP is enabled then the results produced at each 187stage are clamped to the range (0.0, 1.0). If it isn't enabled, results 188are only clamped after the final computation. Since results are always 189clamped after the final texcombine stage, GL_TEXCOMBINE_CLAMP only has 190an effect if more than two textures are enabled. 191 192Texture combine functions can be set for any index regardless of the 193texture enable state. The functions may not be used but it is legal to 194set them. Texture values are treated in a generic way during texture 195combining so there are no inherent restrictions on the formats of the 196textures in the current texture vector. Implementations are encouraged 197to support arbitrary mixtures of texture size, format and 198dimensionality. Applications can determine if an implementation cannot 199support a particular mix of textures through the proxy mechanism. 200 201The default functions are (GL_ONE, GL_ADD, GL_ONE, GL_ONE, GL_ADD, 202GL_ONE). 203 204New capabilities for existing functions: 205 206glGet{*}v 207 208GL_MAX_CURRENT_TEXTURES and GL_CURRENT_TEXTURE_INDEX can be retrieved 209through glGet. The enable state of GL_TEXCOMBINE_CLAMP can be retrieved 210with glGet. GL_TEXCOMBINE_NATURAL_CLAMP's setting can be retrieved with 211glGet. 212 213The current texture combine functions can be retrieved through glGet 214using the GL_TEXCOMBINE_COMBINE_COLORn, GL_TEXCOMBINE_COLOR_OPn, 215GL_TEXCOMBINE_TEX_COLORn, GL_TEXCOMBINE_COMBINE_ALPHAn, 216GL_TEXCOMBINE_ALPHA_OPn and GL_TECOMBINE_TEX_ALPHAn enumerants. 217 218glEnable, glDisable, glIsEnabled 219 220GL_TEXCOMBINE_CLAMP can be enabled, disabled and checked using the 221standard enable functions. 222 223Impact of texture index on existing functions: 224 225glMatrixMode 226 227Each texture coordinate has its own texture matrix so N texture matrices 228must be kept instead of one. 229 230glEnable 231glDisable 232glIsEnabled 233glGet{*}v 234 235All of the textures supported by an implementation can be enabled and 236disabled using the GL_TEXTURE_1D and GL_TEXTURE_2D enumerants. As with 237single texture implementations, if both textures for a particular n are 238enabled then the 2D texture takes precedence. Enabling texture n 239enables all textures between zero and n. Disabling texture n disables 240all textures from n to GL_MAX_CURRENT_TEXTURES-1. This behavior allows 241quick enabling and disabling of multiple textures while preventing 242sparse enable states. 243 244Each enabled texture must be consistent according to the OpenGL rules or 245it is as if texturing is disabled. 246 247glTexImage{12}D 248glCopyTexImage{12}D 249glTexSubImage{12}D 250glCopyTexSubImage{12}D 251glTexParam{if}{v} 252glBindTexture 253glGetTexGen{if}v 254glGetTexParameter{if}v 255glGetTexLevelParameter{if}v 256glGetTexImage 257 258All of the texture control functions must now cope with N times as many 259textures. 260 261Proxies become even more important with multiple texture support as some 262implementations may have restrictions on what kinds of textures can be 263used simultaneously. The proxy mechanism can be used to determine if a 264particular mix of textures is supported or not. 265 266glPushAttrib 267glPopAttrib 268 269All current texture state is pushed and popped. 270 271glMatrixMode 272glPushMatrix 273glPopMatrix 274 275Each texture coordinate has its own transform and texture stack. 276 277Texture Coordinate Generation and Evaluators 278 279Automatically generated texture coordinates affect the n'th texture 280coordinate, where n is the current texture index. N times as many 281texture coordinate generators or texture-coordinate-affecting evaluators 282can now be active. It is invalid to specify evaluator targets other 283than the texture coordinates for non-zero current texture indices. 284 285Other State Queries 286 287All state queries for texture-related information must now return 288information for the currently selected texture. 289 290Change History 291 29204/15/97 293 Changed 'left' to 'combine' and 'right' 294to 'tex' to try and make names more descriptive. 295 Changed all enumerants ending in _n to 296just n to match existing style for consecutive enumerants. 297 Changed TEXCOORD_BIT_n to TEXCOORDn_BIT 298for consistency. 299 30002/06/97 301 Changed glNthTexCoord to glMultiTexCoord 302to allow multiple texture coordinates to be set with a single call. It 303is expected that texture coordinates will commonly be the same for 304multiple textures and there is some hardware that supports texture 305coordinate broadcasting so this is an important programming and 306performance issue. 307 30802/04/97 309 Added GL_TEXCOMBINE_NATURAL_CLAMP to 310give applications a way to determine whether texcombine clamping should 311be enabled or not for maximum performance. 312 31301/27/97 314 Added GL_*_ALPHA_REPLACES_COLOR so that 315alpha values can override color values when doing texture combining. 316 31701/21/97 318 Chose sixteen as the maximum number of 319current textures possibly supported. 320 glBindNthTexture added. 321 glNthTexBlendFunc changed to 322glNthTexCombineFunc. 323 Scaling factors split into separate 324color and alpha factors in glNthTexCombineFunc. New scaling factors 325added and all scaling factors explicitly specified. 326 Combine function query enumerants 327changed and extended to match glNthTexCombineFunc. 328 GL_MULT deleted as an allowed operator 329in glNthTexCombineFunc. 330 GL_TEXCOMBINE_CLAMP added. 331 Changed texture enabled/disable to be 332bulk operations rather than affecting a single texture. 333 Specified that multiple texture 334transforms and stacks must be kept. 335 Encouraged implementations to support 336mixing texture types in the current texture vector. 337 Deleted Questions section as all 338previously open issues have been closed. 339 34001/16/97 341 Initial release. 342