1OpenGL(R) Shading Language Extension Conventions 2 3Last Modified Date: 2006/12/18 4Author Revision: 11 5 6Document Source: the OpenGL Extension Registry at 7 8 http://www.opengl.org/registry/ 9 10Contributors: 11 12 Pat Brown, NVIDIA 13 John Kessenich, 3Dlabs 14 Jon Leech 15 Barthold Lichtenbelt, 3Dlabs 16 Bill Licea-Kane, ATI 17 Kent Lin, Intel 18 Jeremy Sandmel, ATI 19 Folker Schamel, Spinor 20 21The ARB OpenGL Shading Language working group has defined the following 22conventions for writing OpenGL extension specifications that extend the 23Shading Language syntax or semantics. 24 25======================================================================= 26 27Section #1: Conventions to avoid name-space collision 28 29 We expect the Shading Language to continue to evolve through the 30 use of vendor, EXT, and ARB extensions, as well as through 31 revisions to the core language specification itself. As a result, 32 we'd like to establish some name conventions to avoid name-space 33 collisions between vendors and between the extensions and the core 34 language. 35 36 We have the same kinds of concerns that resulted in the need for 37 naming and syntax rules document for the non-shader parts of 38 OpenGL: 39 40 http://www.opengl.org/registry/doc/rules.html#spec_naming 41 42 We expect that we will need to affix new names with vendor tags 43 where appropriate, and change and/or remove these tags as 44 extensions are promoted, in the same fashion as for core GL 45 function and token names. 46 47 The fact that the Shading Language is modeled after C/C++ means 48 that we have some additional requirements for what the language 49 should "look" like. 50 51 Consequently, vendors must use the following naming conventions 52 when creating new OpenGL extensions that affect the syntax of the 53 Shading Language. 54 55 General principles: 56 57 - New syntax defined by an extension should be suffixed with a 58 vendor specific extension (EXT, ARB, SGI, etc), 59 except as noted below where the constraints of 60 being "C-like" make it unpalatble. 61 - Vendors should make a good faith effort to ensure that new 62 shading language extensions do not conflict in syntax or 63 semantics with the extensions of other vendors 64 or the ARB. 65 66 Rules for adding or modifying specific Shading Language 67 constructs defined by extensions follow. 68 69 Note: VEN stands for any vendor tag, e.g. ARB, EXT, SGI, etc. 70 71 Summary: 72 -------- 73 1a) variables: gl_<Name>VEN 74 1b) keywords: __<name>VEN 75 1c) data types: 76 1c1) keywords: __<name>VEN 77 1c2) derived types: gl_<Name>VEN 78 1d) operators: use new data types as operands or ask ARB 79 1e) functions: <name>VEN 80 81 Details: 82 -------- 83 1a) Variables 84 STATUS: RESOLVED 85 86 New variables defined by an extension should use: 87 prefix: "gl_" (lower case, single underscore) 88 suffix: "VEN" (no underscore) 89 90 Form: 91 gl_<Name>VEN 92 93 <Name> is subject to these constraints: 94 - Each word in <Name> must start with a capital letter. 95 - Words should be concatenated, not separated with 96 underscores. 97 - Don't use an underscore to separate the 98 final VEN suffix. 99 100 Notes: 101 All of the variables defined in the core 102 shading language specification already follow this 103 convention. 104 105 New variables added by shading language extensions should 106 match the naming style of the core specification 107 where possible. 108 109 Examples: 110 uniform float gl_SomeNewBuiltinScalarARB; 111 varying vec4 gl_YetAnotherVaryingEXT; 112 attribute vec4 gl_OneMoreAttributeATI 113 114 1b) keywords: 115 STATUS: RESOLVED 116 117 New keywords defined by an extension should use: 118 prefix: "__" (double underscore) 119 suffix: VEN (no underscore) 120 121 Form: 122 __<name>VEN 123 124 Notes: 125 New keywords should be prefixed with "__" because this is 126 how C/C++ handle keyword extensions. The core language 127 specification reserves the use of "__" anywhere within a 128 keyword so that future language revisions from the ARB will 129 not conflict with user level names. 130 131 To avoid name collisions between OpenGL implementations from 132 different IHV's, extended keywords should also use a vendor 133 suffix. 134 135 The working group considered requiring a "gl_" for the 136 prefix instead of "__", but felt this diverged too far from 137 the conventions of C/C++ 138 139 Examples: 140 __float4EXT 141 __sampler4DSGI 142 __elifARB 143 __some_new_kind_of_while_loopARB 144 145 1c) New data types: 146 STATUS: RESOLVED 147 148 Naming conventions for new data types defined by an extension 149 differ depending on whether the data type is a new fundamental 150 type defined as a keyword (case 1c1), or a new derived type 151 defined by Shading Language constructs (case 1c2). Currently the 152 only derived types are "struct"s. 153 154 1c1) For new data type keywords defined by an extension: 155 156 prefix: "__" (double underscore) 157 suffix: VEN 158 159 Form: 160 __<name>VEN 161 162 Examples: 163 __float4SGI 164 __half2NV 165 __triplefloatARB 166 __mat5EXT 167 168 1c2) For new derived types defined by an extension: 169 170 prefix: "gl_" (gl and single underscore) 171 suffix: VEN 172 173 Form: 174 gl_<name>VEN 175 176 Examples: 177 gl_skinningParametersEXT 178 gl_newDerivedStateStructARB 179 180 Notes: 181 If new data types are defined as keywords, then they 182 should follow the rules for keywords. If new data types 183 are derived types, then they should follow a different 184 naming convention, like the one for variables. 185 186 New data types should not be added as keywords unless 187 absolutely necessary. 188 189 1d) New operators: 190 STATUS: RESOLVED 191 192 To avoid name space collisions for new operators 193 defined by an extension, or existing operators whose 194 behavior is re-defined by an extensions, extensions should 195 either: 196 197 1d1) Add a new data type along with the operator and use at 198 least one of these new data types for the operands of the 199 (re)defined operator. The new data type name should follow 200 the rules given in (1c) above for new data types. 201 202 or 203 204 1d2) For IHVs who want to define a new operator to work on 205 existing data types or to redefine an existing operator to 206 work on existing data types, the IHV should come to the ARB 207 and request the new operator to avoid colliding with any 208 upcoming uses for the operator by the ARB. 209 210 Examples: 211 An extension which overloads the "+" operator to add an int 212 and a "triple" should define a new gl_tripleEXT type, then 213 define the behavior of the + operator when one operand is an 214 int and the other is a gl_tripleEXT. 215 216 An extension needing to overload the "+" operator to add an 217 int and a float must obtain permission from the ARB. If it 218 approves, the ARB would revise the shading language grammar 219 to define the behavior of the + operator when one operand is 220 an int and the other is a float. 221 222 An extension needing to define an entirely new operator for 223 exponentiation must obtain permission from the ARB. If it 224 approves, the ARB would agree to reserve an appropriate new 225 operator, such as "**", and the extension would define the 226 behavior of that operator with respect to some data types. 227 228 Notes: 229 On the surface, operators by themselves need no additional 230 name-space syntax. No one wants "+" redefined as gl_+ARB, for 231 instance. 232 233 However, the ARB still wants to avoid name space and semantic 234 collisions as extensions are promoted. The ARB reserves the 235 use of operators with existing types. 236 237 Therefore we've adopted the two-pronged approach listed above. 238 (A) is borrowed from C++ operator overloading conventions. 239 (B) is a fall-back position in the event that (A) is 240 inconvenient. 241 242 1e) functions: 243 STATUS: RESOLVED 244 245 New functions defined by an extension should use: 246 prefix: none (note, no "gl_" or "__") 247 suffix: VEN 248 249 Form: 250 <name>VEN 251 252 Examples: 253 newfunctionEXT() 254 SomeOtherFuncARB() 255 Yet_Another_FunctionSGI() 256 257 Notes: 258 Since none of the standard core Shading Language functions 259 start with the "gl_" prefix, new functions do not need this 260 prefix either. There is no need to avoid collisions between 261 implementation-defined and user-defined functions, because 262 the Shading Language specifically allows user overloading of 263 built-in functions. In other words, name collisions are 264 expected and intentional. Further, when a name collision 265 occurs between a user function and an implementation-defined 266 function, the user function takes precedence. 267 268 However, we still must avoid name collisions between IHV's 269 and to allow for promotion of new functions into EXT, ARB 270 and core status. So, new functions should use a VENDOR 271 suffix. 272 273 274============================================================= 275 276Section #2: Protocol for accessing extension features in the 277 shading language 278 279 2a) Extension #defines? 280 281 STATUS: RESOLVED 282 283 Every extension which affects shading language semantics or 284 syntax must create a Shading Language preprocessor #define that 285 matches the GL extension name string. This #define would be 286 available in the shading language if and only if the extension 287 were supported on a given Shading Language implementation. 288 289 Further, extensions which do not affect shading language 290 semantics or syntax *must not* create this Shading Language 291 preprocessor #define. 292 293 The extension-writing template in the OpenGL Extension Registry 294 will be updated to include a placeholder for shading language 295 extensions showing the corresponding #define. 296 297 Example: 298 An extension which adds the extension string 299 "GL_ARB_shading_extension_1" 300 should also add a Shading Language preprocessor #define called 301 GL_ARB_shading_extension_1 302 303 Doing so means that a shader can do something like: 304 305 #ifdef GL_ARB_shading_extension_1 306 // do something using the extension 307 #else 308 // do something else or #error! 309 #endif 310 311 Notes: 312 If an application wishes to emulate this behavior for any 313 other extensions which do not directly affect the shading 314 language syntax or behavior, they can simply query the 315 extension string for the presence of these extensions and 316 create their own #defines to be prepended to their shader 317 strings. 318 319 Pseudo-code example: 320 char* prefixStr; 321 if (glIsExtensionSupported("GL_ARB_texture_mirrored_repeat")) 322 { 323 ConcatString(prefixStr, "#define GL_ARB_texture_mirrored_repeat 1\n"); 324 } 325 // use prefixStr as the first string given to glShaderSource() 326 327 2b) Should we allow and/or require a shader author to declare 328 their intended use of a given extension prior to use? 329 330 STATUS: RESOLVED - YES 331 332 The ARB has received developer feedback requesting we strive 333 towards portability in the shading language. The concern is 334 shaders written on one implementation with an extension will not 335 run on an implementation without the extension and that without 336 an explicit "enable", the shader author may not realize that 337 he/she was using any extended features. 338 339 After much discussion, the resolution is as follows: 340 341 For any extension which can affect shaders written without 342 knowledge of the extension (i.e. no change in syntax to the 343 shading language), the extension must introduce an API which 344 explicitly "enables" the extended behavior. New extensions 345 should not be allowed to change the behavior of old shaders 346 without an explicit request to do so from the application. 347 348 Further, for any extension which affects the syntax or semantics 349 of the shading language, the shader author must explicitly make 350 a request allow the use of the extension, by inserting this 351 request within the shader text itself. 352 353 This request is made using the following syntax: 354 #extension <name> : <behavior> 355 where 356 <name> = the GL extension name string (as defined in section 2a, 357 starting with "GL_"). 358 and 359 <behavior> can be one of the following: 360 require, enable, warn, or disable 361 362 Example: 363 To use an extension which adds the extension string 364 "GL_ARB_shading_extension_1", a shader should include a line like: 365 366 #extension GL_ARB_shading_extension_1: enable 367 368 See section 3.3 of the OpenGL Shading Language specification 369 (Language Version 1.20) for details about using this mechanism. 370 371----------------------------------- 372 373Revision history: 374 375 #11 - 12/18/2006 - Jon Leech 376 - Clarify that #extension name must be the extension name string 377 starting with "GL_", give an example, fix an old URL. 378 379 #10 - 10/09/2006 - Jon Leech 380 - Move registry URL to www.opengl.org. 381 382 #9 - 05/12/2004 - js 383 - no changes from rev #8, whitespace cleanup only 384 385 #8 - 05/11/2004 - js 386 - minor typos fixed 387 - cleaned up language about when to use 1c1 or 1c2 388 389 #7 - 05/07/2004 - Jon Leech 390 - language cleanups including removing use of "built in" 391 392 #6 - 04/29/04 - js 393 - cleaned up psuedo code example in section 2a 394 - change language about "decorate"ing names to "affix" 395 396 #5 - 04/29/04 - js 397 - added to contributors list 398 399 #4 - 04/29/04 - js 400 - cleaned up section 2 to reflect #extension resolution 401 402 #3 - 03/15/04 - js 403 - summarized section 1 conventions on name decorations 404 405 #2 - 03/24/04 - js 406 - reorganized doc to reflect recent working group discussions 407 408 #1 - 03/19/04 - js 409 - initial revision 410