1Name 2 3 ARB_shading_language_include 4 5Name Strings 6 7 GL_ARB_shading_language_include 8 9Contact 10 11 Jon Leech (jon 'at' alumni.caltech.edu) 12 13Notice 14 15 Copyright (c) 2010-2013 The Khronos Group Inc. Copyright terms at 16 http://www.khronos.org/registry/speccopyright.html 17 18Specification Update Policy 19 20 Khronos-approved extension specifications are updated in response to 21 issues and bugs prioritized by the Khronos OpenGL Working Group. For 22 extensions which have been promoted to a core Specification, fixes will 23 first appear in the latest version of that core Specification, and will 24 eventually be backported to the extension document. This policy is 25 described in more detail at 26 https://www.khronos.org/registry/OpenGL/docs/update_policy.php 27 28Status 29 30 Complete. Approved by the ARB at the 2010/01/22 F2F meeting. 31 Approved by the Khronos Board of Promoters on March 10, 2010. 32 33Version 34 35 Version 17, June 24, 2013 36 37Number 38 39 ARB Extension #76 40 41Dependencies 42 43 A version of OpenGL supporting OpenGL Shading Language 1.10 or later 44 is required. 45 46 This extension is written against the OpenGL 3.2 (Core Profile) and 47 OpenGL Shading Language 1.50 Specifications. 48 49Overview 50 51 This extension introduces a #include GLSL directive to allow reusing 52 the same shader text in multiple shaders and defines the semantics 53 and syntax of the names allowed in #include directives. It also 54 defines API mechanisms to define the named string backing a 55 #include. 56 57IP Status 58 59 No known IP claims. 60 61New Procedures and Functions 62 63 void NamedStringARB(enum type, int namelen, const char *name, 64 int stringlen, const char *string) 65 void DeleteNamedStringARB(int namelen, const char *name) 66 67 void CompileShaderIncludeARB(uint shader, sizei count, 68 const char *const *path, 69 const int *length) 70 71 boolean IsNamedStringARB(int namelen, const char *name) 72 void GetNamedStringARB(int namelen, const char *name, 73 sizei bufSize, int *stringlen, 74 char *string) 75 void GetNamedStringivARB(int namelen, const char *name, 76 enum pname, int *params) 77 78New Tokens 79 80 Accepted by the <type> parameter of NamedStringARB: 81 82 SHADER_INCLUDE_ARB 0x8DAE 83 84 Accepted by the <pname> parameter of GetNamedStringivARB: 85 86 NAMED_STRING_LENGTH_ARB 0x8DE9 87 NAMED_STRING_TYPE_ARB 0x8DEA 88 89Additions to Chapter 2 of the OpenGL 3.2 Specification (OpenGL Operation) 90 91 Add new section 2.11.1 preceding the current section 2.11.1 and 92 renumber following sections: 93 94 "2.11.1 Named Strings 95 96 Arbitrary strings may be defined and given names. These strings can 97 be included by name in shaders during compilation, allowing reuse of 98 the same code segments. A string and its name are specified 99 with the command 100 101 void NamedStringARB(enum type, int namelen, const char *name, 102 int stringlen, const char *string) 103 104 <type> must be SHADER_INCLUDE_ARB. <namelen> is the number of 105 <char>s in <name>. <name> defines the name associated with the 106 string. <stringlen> is the number of <char>s in <string>. <string> 107 is an arbitrary string of characters. If <namelen> or <stringlen> 108 are negative, then <name> or <string> respectively are considered to 109 be null-terminated strings. 110 111 <name> must be a <valid pathname> as defined in Appendix A of the 112 OpenGL Shading Language Specification. Additionally, <name> must 113 begin with the character '/'. Before creating a named string, <name> 114 is converted to a <tree location> as described in Appendix A of 115 the OpenGL Shading Language Specification. 116 117 After calling NamedStringARB, the contents of <string> are 118 associated with the tree location corresponding to <name>[fn1]. If a 119 string is already associated with that tree location, it will be 120 replaced with the new <string>. 121 [fn1 - Many possible <name>s may correspond to the same tree 122 location.] 123 124 An INVALID_VALUE error will be generated under any of the following 125 conditions: 126 127 - Either <name> or <string> is NULL. 128 - <name> is not a valid pathname beginning with '/'. 129 130 To delete a named string, use the command 131 132 void DeleteNamedStringARB(int namelen, const char *name) 133 134 <namelen>, and <name> have the same meanings as the corresponding 135 parameters of NamedStringARB. After calling DeleteNamedStringARB, no 136 string is associated with the tree location corresponding to <name>. 137 138 An INVALID_VALUE error will be generated under any of the following 139 conditions: 140 141 - <name> is NULL. 142 - <name> is not a valid pathname beginning with '/'. 143 144 An INVALID_OPERATION error will be generated if the tree location 145 corresponding to <name> has no string associated with it." 146 147 148 Replace the description of CompileShader in new section 2.11.2 149 (formerly section 2.11.1) with: 150 151 "Once the source code for a shader has been loaded, a shader object 152 can be compiled with the command 153 154 void CompileShaderIncludeARB(uint shader, sizei count, 155 const char * const *path, 156 const int *length) 157 158 <path> is an ordered array of <count> pointers to optionally 159 null-terminated character strings defining <search paths>. <length> 160 is an array of <count> values with the number of chars in each 161 string (the string length). If an element in <length> is negative, 162 its accompanying string is null-terminated. If <length> is NULL, all 163 strings in the <path> argument are considered null-terminated. 164 165 Each string in <path> must be a valid <pathname> as defined in 166 Appendix A of the OpenGL Shading Language Specification, and must 167 begin with the character '/'. The ordered list of <path>s is used 168 during compilation, together with the arguments of #include 169 directives in the shader source, to search for named strings 170 corresponding to the #include directives as described in section 171 3.3 of the OpenGL Shading Language Specification. If a #include 172 directive does not correspond to a valid named string, compilation 173 will fail. 174 175 Each shader object has a boolean status that is modified as a result 176 of compilation, and can be queried by calling GetShaderiv (see 177 section 6.1.10) with <pname> COMPILE_STATUS. The status will be set 178 to TRUE if <shader> was compiled without errors and is ready for 179 use, and FALSE otherwise. Compilation can fail for a variety of 180 reasons as listed in the OpenGL Shading Language Specification. If 181 compilation failed, any information about a previous compile is 182 lost. Thus a failed compile does not restore the old state of 183 shader. 184 185 Changing the source code of a shader object with ShaderSource, or 186 the contents of any named strings corresponding to #include 187 directives in the source code, does not change its compile status or 188 the compiled shader code. 189 190 Each shader object has an information log, which is a text string 191 that is overwritten as a result of compilation. This information log 192 can be queried with GetShaderInfoLog to obtain more information 193 about the compilation attempt (see section 6.1.10). 194 195 An INVALID_OPERATION error is generated if <shader> is not the name 196 of a valid shader object generated by CreateShader. 197 198 An INVALID_VALUE error will be generated under any of the following 199 conditions: 200 - <count> is greater than zero and <path> is NULL, or any 201 of the pointers path[0] .. path[<count>-1] is NULL. 202 - Any of the strings in <path> are not valid pathnames beginning 203 with '/'. 204 205*** (compatibility profile only) 206 An INVALID_OPERATION error is generated if CompileShaderIncludeARB 207 is executed between Begin and the corresponding End. 208 209 The command 210 211 CompileShader(uint shader) 212 213 is equivalent to 214 215 CompileShaderIncludeARB(shader,0,NULL,NULL). 216 217 Shader objects can be deleted with the command ..." 218 219 220Additions to Chapter 5 (Special Functions) 221 222 Add CompileShaderIncludeARB to the list of "Commands Not Usable In 223 Display Lists" in section 5.4.1 of the compatibility profile. 224 225Additions to Chapter 6 (State and State Requests) 226 227 Add new section 6.1.10 preceding the current section 6.1.10 and 228 renumber following sections: 229 230 "6.1.10 Named String Queries 231 232 The command 233 234 boolean IsNamedStringARB(int namelen, const char *name) 235 236 returns TRUE if the tree location corresponding to <name> has a 237 string associated with it, and FALSE if the tree location has no 238 string associated with it. <name> and <namelen> have the same 239 meanings as the corresponding parameters of NamedStringARB (see 240 section 2.11.1). 241 242 If <name> or <namelen> do not describe a valid name, or if <name> is 243 NULL, IsNamedStringARB succeeds and returns FALSE. 244 245 The command 246 247 void GetNamedStringivARB(int namelen, const char *name, 248 enum pname, int *params) 249 250 returns properties of the named string whose tree location 251 corresponds to <name>. <name> and <namelen> have the same meanings 252 as the corresponding parameters of NamedStringARB (see section 253 2.11.1). The parameter value to return is specified by <pname>. 254 255 If <pname> is NAMED_STRING_LENGTH_ARB, the length of the named 256 string, including a null terminator, is returned. If <pname> is 257 NAMED_STRING_TYPE_ARB, the <type> argument passed to NamedStringARB 258 is returned. 259 260 An INVALID_VALUE error will be generated under any of the following 261 conditions: 262 263 - <name> is NULL. 264 - <name> is not a valid pathname beginning with '/'. 265 266 An INVALID_OPERATION error will be generated if the tree location 267 corresponding to <name> has no string associated with it. 268 269 The command 270 271 void GetNamedStringARB(int namelen, const char *name, 272 sizei bufSize, int *stringlen, 273 char *string) 274 275 returns in <string> the string corresponding to the specified 276 <name>. <name> and <namelen> have the same meanings as the 277 corresponding parameters of NamedStringARB. 278 279 The returned string will be null-terminated. The actual number of 280 characters written into <string>, excluding the null terminator, is 281 returned in <stringlen>. If <stringlen> is NULL, no length is 282 returned. The maximum number of characters that may be written into 283 <string>, including the null terminator, is specified by <bufSize>. 284 285 An INVALID_VALUE error will be generated under any of the following 286 conditions: 287 288 - <name> is NULL. 289 - <name> is not a valid pathname beginning with '/'. 290 291 An INVALID_OPERATION error will be generated if the tree location 292 corresponding to <name> has no string associated with it." 293 294 295Additions to Appendix D of the OpenGL 3.2 Specification (Shared Objects and 296Multiple Contexts) 297 298 Add "named strings" to the list of shared object types in the second 299 paragraph of Appendix D, prior to "program and shader objects". 300 301 302 Replace the second paragraph of section D.1.2 with: 303 304 "When a named string, shader object, or program object is deleted, it 305 is flagged for deletion, but its name remains valid until the 306 underlying object can be deleted because it is no longer in use. A 307 named string is in use for the duration of any 308 CompileShaderIncludeARB command [fn3]. A shader object is in use 309 while it is attached to any program object. A program object is in 310 use while it is the current program in any context. 311 [fn3 - this effectively places a lock around the named string 312 dictionary during compilation. Given the lack of ordering 313 inherent in multicontext access to the named string database it 314 would probably be equally acceptable to state that the effect of 315 deleting or changing a named string from one context during 316 compilation in another context is undefined.] 317 318 Named strings are treated as invariant while they are in use during 319 compilation of a shader. That is, named strings will not be added 320 to, changed, or removed from the point of view of 321 CompileShaderIncludeARB, even if such changes are made in other 322 contexts [fn4]. 323 [fn4 - implementations may use locking, caching, or other 324 techniques to realize such invariance. Again this effectively 325 places a lock around the dictionary in order to provide 326 predictable multicontext behavior across all implementations.]" 327 328 Add to the list of <data> in the first paragraph of section D.3: 329 330 "- Named strings (only string contents, not string names)." 331 332 Add a new paragraph to the first bullet point, describing the term 333 <directly attached>, in section D.3.2: 334 335 "Additionally, a named string object T will be considered to have 336 been <directly attached> to the current context whenever a 337 CompileShaderIncludeARB command is issued, and to have been 338 detached when that CompileShaderIncludeARB completes." 339 340 (This language may need some iteration. The intent is that whenever 341 CompileShaderIncludeARB is called, the effect is to pick up all 342 changes to the named string dictionary completed in other contexts 343 prior to that compilation by leveraging the existing "directly 344 attached" language of Appendix D instead of introducing a new type 345 of relationship between object and context, even though named 346 strings are not "bound".) 347 348 349Additions to Chapter 3 of the OpenGL Shading Language 1.50 Specification 350 351 Including the following line in a shader will enable #include and 352 related extended language features described in this extension: 353 354 #extension GL_ARB_shading_language_include : <behavior> 355 356 where <behavior> is as specified in section 3.3 for the #extension 357 directive. 358 359 360 Add a new class of characters following the first paragraph 361 of section 3.1 "Character Set": 362 363 "The double quote ( " ) for use only with #include and #line." 364 365 Replace the next-to-last paragraph of section 3.1 with: 366 367 "There are no character or string data types, with the exception of 368 the quoted string used to name an include string for the 369 preprocessor." 370 371 372 Add following the first paragraph of section 3.2: 373 374 "A shader can also include another string, using #include, as 375 described later. The included string is a single string, not an 376 array of strings, but this string may itself include other strings." 377 378 Replace the last paragraph of section 3.2 with: 379 380 "Diagnostic messages returned from compiling a shader must identify 381 both the line number within a string and which source string the 382 message applies to. For included strings (using #include), the 383 string is identified by the path provided in the shader to the 384 #include statement. For an array of shader source strings, strings 385 are counted sequentially with the first string being string 0. Line 386 numbers are one more than the number of new-lines that have been 387 processed. These are all consistent with use of the __LINE__, 388 __FILE__, and __FILE_SPACE__ macros as described below." 389 390 Add to the list of preprocessor directives in the second paragraph 391 of section 3.3: 392 393 "#include" 394 395 Add following the paragraph in section 3.3 starting "The number 396 sign...": 397 398 "Functionality for #include is dependent on the GL to supply a tree 399 of strings to search, plus an ordered list of initial search points 400 within that tree. The presence of these is assumed below. 401 402 The #include directive is followed by a quoted <path>; a string 403 quoted with double quotes or angled brackets ( < > ): 404 405 #include "path" 406 #include <path> 407 408 This will lookup <path> in the supplied tree, as described in Appendix 409 A, and select its associated string. The associated string is 410 substituted and processed as is standard for C++ preprocessors, with 411 full preprocessing applied after the substitution. It is a 412 compile-time error if <path> is not valid as described in Appendix 413 A. 414 415 If <path> starts with a forward slash, whether it is quoted with 416 double quotes or with angled brackets, the list of search points is 417 ignored and <path> is looked up in the tree as described in Appendix 418 A. It is a compile-time error if a path starting with a forward 419 slash either 420 421 * exists in the tree, but does not have a string associated with 422 it, or 423 * does not exist in the tree. 424 425 If <path> does not start with a forward slash, it is a path relative 426 to one of the ordered list of initial search points. If this path is 427 quoted with angled brackets, the tree is searched relative to the 428 first search point in the ordered list, and then relative to each 429 subsequent search point, in order, until a matching path is found in 430 the tree. This is also the behavior if it is quoted with double 431 quotes in an initial (non-included) shader string. If it is quoted 432 with double quotes in a previously included string, then the first 433 search point will be the tree location where the previously included 434 string had been found. If not found there, the search continues at 435 the beginning of the list of search points, as just described. It is 436 a compile error if 437 438 * the first time the path is found in the tree relative to a 439 search point, there is no string assigned to that path 440 * the path is not found relative to any of the search points." 441 442 Replace the paragraph of section 3.3 starting with '__FILE__ 443 will...' with: 444 445 "__FILE__ will substitute either a decimal integer constant that says 446 which source string number is currently being processed, or the path 447 of the string if the string was an included string. This path will 448 be the same as the path supplied to the #include directive." 449 450 Replace the last paragraph of section 3.3 with: 451 452 "#line must have, after macro substitution, one of the following 453 forms: 454 455 #line <line> 456 #line <line> <source-string-number> 457 #line <line> "<path>" 458 459 where <line> and <source-string-number> are constant integer 460 expressions and <path> is a valid string for a path supplied in the 461 #include directive. After processing this directive (including its 462 new-line), the implementation will behave as if it is compiling at 463 line number <line> and source string number <source-string-number> 464 or <path> path. Subsequent source strings will be numbered 465 sequentially, until another #line directive overrides that 466 numbering." 467 468Additions to Appendix A (Looking up Paths in Trees) of the OpenGL 469Shading Language 1.50 Specification 470 471 Add a new appendix A: 472 473 "Appendix A: Looking up Paths in Trees 474 475 Introduction 476 477 The GLSL #include mechanism looks up paths in a tree built through 478 the OpenGL API. This appendix describes the syntax and semantic 479 model of the tree and paths into the tree. How the tree is used is 480 up to users of the tree, like the OpenGL API or GLSL. 481 482 The Tree 483 484 The tree is a singly rooted hierarchy of tree locations. The root 485 may have one or more child locations, and any location may in turn 486 have its own children. Except for the root, each location has 487 exactly one parent; the root has no parent. 488 489 Paths into the Tree 490 491 The locations in the tree are created or looked up by path strings. 492 The path string "/" locates the root of the tree. The path "/foo" 493 locates the child "foo" of the root. Formally, a valid path is a 494 sequence of tokens delimited by the beginning of the string, by the 495 path-separator forward slash ( / ), and by the end of the string. 496 The string "foo/bar" has two tokens; "foo" and "bar". The string 497 "/foo/./bar" has 3 tokens; "foo", ".", and "bar". The string 498 "/foo/.." has two tokens; "foo" and "..". The string "/foo/.bar" has 499 two tokens; "foo" and ".bar". A path is invalid if 500 501 * <path> contains any characters not listed in Section 3.1 502 "Character Set", or the double quote character, or angled 503 brackets, or any white space characters other than the space 504 character, 505 * <path> has consecutive forward slashes ( // ); "/foo//bar" is 506 not valid (zero length tokens are not allowed), 507 * <path> ends with a forward slash ( / ), or 508 * <path> contains no characters. 509 510 There are no path escape characters, so there is no way to get the 511 forward slash delimiter within a single token. 512 513 When using a path to lookup a tree location, the path tokens are 514 used to walk the tree. The initial location to start the walk is 515 specified by the user of the tree and is updated as follows by the 516 tokens in the path. (Paths starting with "/" will start at the 517 root.) Taken left to right: 518 519 The token ".." walks to the parent. Or, if already at the root, then 520 the location remains at the root. 521 522 The token "." leaves the location unchanged. 523 524 Any other token is considered the name of a child of the current 525 location, and walks to that child. (If there is no child of that 526 name, this may result in a failed lookup or in the child being 527 created, as specified by the user of the tree for the operation 528 being performed.) 529 530 Associated Strings 531 532 Each location in the tree can have an additional string associated 533 with it (that a user like the #include mechanism can use as an 534 included string). This is true even for locations that have 535 children: "/foo/bar" can exist in the tree at the same time that 536 "/foo" has an additional string associated with it. Typically, when 537 a path is used to find a location in the tree, it is for the purpose 538 of returning this associated string. 539 540 Hence, the tree can be built from a collection of (path,string) 541 pairs, where path is a string establishing the existence of a 542 location in the tree and string is the string associated with the 543 node. Details of how to do this are specified by the user of the 544 tree." 545 546Additions to the AGL/GLX/WGL Specifications 547 548 None. 549 550GLX Protocol 551 552 To be determined. 553 554Errors 555 556 <fill in from spec language above> 557 558New State 559 560 Add new state table 6.46 and renumber existing 561 tables starting at 6.47: 562 563 "Table 6.46: Named String State 564 565 Get Value Initial Value Get Command Type Description Sec. Attribute 566 --------- ------------- ---------------- ------ --------------------- ------ --------- 567 NAMED_STRING_LENGTH_ARB -- GetNamedStringivARB n x Z+ Named string length 6.1.10 -- 568 NAMED_STRING_TYPE_ARB -- GetNamedStringivARB n x Z_1 Named string type 6.1.10 -- 569 -- -- GetNamedStringARB n x S Named string contents 6.1.10 --" 570 571Revision History 572 573 Rev. Date Author Changes 574 ---- -------- --------- ------------------------------------------ 575 17 13/06/24 Jon Leech 576 - Add additional 'const' attribute to CompileShaderIncludeARB 577 <path> (Bug 9006). 578 16 10/02/10 Jon Leech 579 - Remove 'const' attribute from GetNamedStringARB <stringlen>. 580 15 10/01/27 Jon Leech 581 - Update issues. Minor corrections from John Kessenich. 582 14 10/01/26 pbrown 583 - Assigned enumerant values. 584 13 10/01/26 Jon Leech 585 - Restore ARB suffixes. 586 12 10/01/25 Jon Leech 587 - Merge major edits from GLSL 1.60 (now GLSL 3.30). 588 11 10/01/14 Jon Leech 589 - Sync up with minor edits to the GL 3.3 API spec language. Major 590 edits to the GLSL 1.60 spec language are still to be pulled back 591 into the extension. 592 10 09/11/12 Jon Leech 593 - Remove redundant <namelen> == zero errors, since an empty name 594 is not a valid pathname. 595 - Change "match" to "have the same meanings as" when describing 596 parameters common to multiple commands. 597 - Make errors for CompileShaderInclude consistent and more 598 robust against NULL pointers. 599 - Confirm that IsNamedString does not generate errors due to 600 otherwise invalid names. 601 - Added Bruce's comments on sharing to issue 4. 602 9 09/10/30 Jon Leech 603 - Replace "canonical pathname" with "tree location". 604 - Add NAMED_STRING_TYPE query. 605 - Add new state table with named string parameters and contents. 606 - Add issue 20 on why there are no examples. 607 8 09/10/29 Jon Leech 608 - Add GetNamedStringiv query for named string length. 609 - Add requirement to pathname rule 3 that #include strings and 610 string names may not end in '/', but search paths may end in 611 '/'. 612 - Change type of 'namelen' and 'stringlen' parameters from sizei 613 to int to allow specifying null-termianted strings. 614 - Finish removing references to namespaces from GLSL language. 615 7 09/10/28 Jon Leech 616 Many changes from group discussion: 617 - Rename extension to ARB_shading_language_include by 618 symmetry with ARB_shading_language_100. 619 - Remove namespace objects and go back to a single shared named 620 string dictionary. 621 - Remove __FILE_NAMESPACE__ macro from shader language. 622 - Pass multiple path strings to CompileShaderInclude, instead of 623 multiple namespace objects. 624 - Require all string names and paths specified through the API to 625 start with '/'. 626 - Support both #include <name> and #include "name" and try to make 627 usage correspond to expectations of C/C++ programmers. 628 - Allow "." and ".." in pathnames and otherwise refine 629 rules on allowed paths. 630 - Introduce concept of canonical pathnames as the key in 631 the named string dictionary. 632 - Added GetNamedString query for completeness. 633 - Still need to expand bullet list of #include behavior into GLSL 634 spec language. 635 - Updated sharing model. 636 6 09/10/15 Jon Leech 637 - Change type of CompileShaderInclude <length> parameter to sizei. 638 - Add GLSL spec edits from John Kessenich, related issues 16-18, 639 and describe the required #extension line. 640 - Use #include <name> instead of #include "name" (see issue 15). 641 - Fix type of CompileShaderInclude <length> parameter. 642 - Make namespace contents invariant for the duration of 643 CompileShaderInclude (from the point of view of the code being 644 compiled). 645 - Update sharing and object model issues 4 and 8 and corresponding 646 Appendix D and error language in the spec. 647 - Fix typos. 648 5 09/10/14 Jon Leech 649 - Rewritten to add namespaces as proposed by Daniel Koch. 650 - Use the shader and program object model for namespace objects. 651 - Change the appendix D language for how multicontext changes to 652 namespaces and names are handled 653 - Update all the issues. 654 4 09/10/04 Jon Leech Add more issues from email discussion 655 3 09/09/24 Jon Leech Define named strings as shared resources 656 2 09/09/24 Jon Leech Fix name of DeleteNamedString 657 1 09/09/24 Jon Leech Initial revision for the Phoenix F2F mtg 658 659Issues 660 661 1) Should names be global, per-program, or per-shader? 662 663 RESOLVED: names are global across the context share list. This 664 is desirable since the point of #include is to reuse as much 665 content as possible. 666 667 2) Should named strings be specified in the API with a single 668 string, or with an array of strings like ShaderSource? 669 670 RESOLVED: a single string. 671 672 3) Are there any constraints on the contents of string names and 673 strings? 674 675 RESOLVED: There are constraints on string names when a named 676 string is defined, deleted, or queried. Names must be valid GLSL 677 pathnames and must also begin with '/'. Additionally string 678 names are converted to tree locations prior to defining a 679 string. 680 681 There are no definition-time constraints on string contents, 682 though of course #include directives must expand to legal source 683 in the shader being compiled, or compilation will fail. 684 685 4) How full-featured are named string objects? 686 687 PROPOSED: named strings are full-fledged objects, although they 688 are objects whose names are "tree locations" corresponding to 689 strings specified in the API, instead of GLuint handles. 690 691 Named strings are intended to be very simple objects which will 692 be infrequently created, updated, or deleted, so naming them by 693 passing string names should be fast enough for this use. There 694 is an IsNamedString query, but there is no way to iterate over 695 all the strings (just as there is no way to iterate over all the 696 names of any other class of object in OpenGL). 697 698 UNRESOLVED: we still need to make sure the proposed sharing 699 rules will make sense and address all the special cases. 700 Bruce offered the following comments on spec language: 701 702 "When a named string, shader object, or program object is 703 deleted, it is flagged for deletion, but its name remains valid 704 until the underlying object can be deleted because it is no 705 longer in use." 706 707 Bruce: I think there are potentially some problems with this. 708 Consider an app routine that does something like this: 709 710 1. Walks some directory tree on the FS 711 2. Suck in all the contents, make named strings out of them. 712 3. CompileShaderIncludes 713 4. Deletes the named strings it created. 714 715 Now suppose this routine is used twice, and at the same time 716 another thread/context calls CompileShaderIncludes (even 717 implicitly via CompilerShader, with no #includes in the source) 718 - according to the language below, this still causes the entire 719 database to become attached. If this other CompileShaderIncludes 720 starts just before step 4 the first time round, and end just 721 before step 3 the second time around, then all the deletions 722 suddenly kick in right before we were about to call the 723 compiler. So even though these compilations used completely 724 disjoint sets of objects, they still managed to cause spooky 725 action at a distance. 726 727 "[fn4 - implementations may use locking, caching, or other 728 techniques to realize such invariance. Again this effectively 729 places a lock around the dictionary in order to provide 730 predictable multicontext behavior across all implementations.]" 731 732 Bruce: I don't see how changing names in the middle of 733 compilation is any different from calling ShaderSource in one 734 context at the same time as CompileShader in the other context. 735 Making such guarantees aren't going to make apps that don't 736 synchronise their threads properly magically start working, and 737 they could add a lot of extra complexity to what is supposed to 738 be a very simple system. 739 740 5) Do we need named string queries? 741 742 RESOLVED: Since they are objects (albeit simple ones), we 743 support queries. 744 745 6) The GLSL language is underspecified 746 747 UNRESOLVED: John Kessenich has written up a detailed bullet list 748 defining the behavior of #include and how API string names and 749 #include string arguments are converted to "tree locations". The 750 bullet points has not yet been refined into final spec language. 751 752 7) What is the <type> parameter for? 753 754 RESOLVED: Future expansion. 755 756 8) Are named strings shared? 757 758 RESOLVED: Yes. The update semantics may appear odd because named 759 strings are not explicitly bound to a context; they simply exist 760 in the share list. Appendix D language has been updated to 761 describe treat CompileShaderInclude as a virtual bind point 762 which "directly attaches" all named strings to the context for 763 the duration of any compilation in which they may be used. 764 765 RESOLVED: CompileShaderInclude is defined to use the state of 766 the named string dictionary at the time it is called. Additions 767 or deletions from other contexts will not affect an ongoing 768 compile. This might be implemented with any combination of 769 techniques such as locks, reference counting against deletion, 770 caching context-local copies, etc. This should produce 771 well-defined behavior without overly constraining implementation 772 choices. 773 774 9) What is the binding point at which #include strings are 775 associated with shaders? 776 777 RESOLVED: CompileShaderInclude. Since the string associated with 778 a name can change over time, for predictability we must specify 779 when a shader expands #include directives. CompileShaderInclude 780 is the only logical place to do this. 781 782 If there are any implementations which defer compilation, they 783 will probably have to do extra work in CompileShaderInclude to 784 cache the named string contents at that time. 785 786 10) Who is responsible for creating the named string dictionary? 787 788 RESOLVED: The app. This extension provides mechanism, not 789 policy, and there is no realistic and portable way for a GL 790 implementation to guess what #include directives are supposed to 791 mean. However, it's straightforward to provide utility libraries 792 which read a particular directory tree of files and define them 793 as a corresponding set of named strings in GL. 794 795 In the future, it would be possible for a layered extension to 796 allow directly searching the client filesystem by passing 797 special searchpaths to CompileShaderInclude. For example, the 798 path "//usr/include/GL", which is not a valid search path in 799 this extension, could be defined to search starting in 800 /usr/include/GL on the client filesystem. There are a number of 801 thorny pitfalls in such usage (for example portability and 802 implementability on separate client/server hardware) and we do 803 not feel a need to support such usage initially. 804 805 11) Do we need to provide a "#once" or "#pragma once" directive to 806 protect against re-inclusion of headers, and possible infinite 807 loops of #includes? 808 809 RESOLVED: No (by straw poll of the Nextgen TSG on 2009/10/19). 810 Instead the 811 812 #ifndef FOO_H 813 #define FOO_H 814 ... 815 #endif /* FOO_H */ 816 817 approach can be used. See discussion of this feature in C: 818 819 http://en.wikipedia.org/wiki/Pragma_once 820 821 12) What other approaches for named strings exist? 822 823 Alternatives we experimented with were a new shader type along 824 with a #name or glShaderName() directive, or explicit "include 825 space" objects in which named strings exist, instead of what is 826 effectively a single implicit "include space" object as in this 827 proposal. 828 829 13) Should we impose syntax and namespace rules on string names? 830 831 RESOLVED: String names (API) and search paths / #include 832 pathnames (GLSL) are expressed in a syntax supporting many Unix 833 pathnames as well as the "." and ".." directives, and must be in 834 the valid GLSL character set. Exact rules define how #include 835 pathnames are searched for in the named string database. 836 837 RESOLVED: We do not impose any namespace rules on string names 838 or search paths. 839 840 PROPOSED: We suggest that string names starting with "/GL/" be 841 reserved to Khronos, but do not enforce this, and also suggest 842 that applications use consistent conventions on pathnames, such 843 as defining named strings under "/<vendorname>/path" and 844 referring to them by that same name in #include directives. 845 846 14) Is this an extension or a "feature specification"? 847 848 RESOLVED: An extension. We decided not to put #include into 849 OpenGL 3.3 / 4.0 yet. 850 851 15) How are nested (and potentially relative) includes handled? 852 853 RESOLVED: Rules like those of a Unix C preprocessor are used to 854 combine #include arguments with the specified compiler search 855 path. 856 857 16) Do we really need to override the source string name with #line? 858 This seems of questionable benefit. 859 860 RESOLVED: Yes. Of utility to automatic code generators like 861 Yacc. 862 863 17) Should 0 or something like -1 be substituted for __FILE_SPACE__ 864 when used in a non-included sting? 865 866 PROPOSED: __FILE_NAMESPACE__ is no longer required, since 867 explicit namespace objects have been removed from the extension. 868 Instead __FILE__ is replaced with something corresponding to the 869 "tree location" of the #include file being processed. 870 871 18) Consistency of API and GLSL string names / pathnames. 872 873 RESOLVED: The API and GLSL validate string names using the same 874 rules, which are defined in the GLSL specification. 875 876 19) Why must string names and search paths in the API start with 877 '/'? 878 879 Because string names and search paths must both be absolute, 880 rather than relative, paths to function as intended. 881 882 20) Should there be examples of names and how multiple names 883 correspond to the same tree location? 884 885 UNRESOLVED. 886