文章目录
原文：extensions/ARB/ARB_shading_language_include.txt
Overview - 概述
This extension introduces a #include GLSL directive to allow reusing
the same shader text in multiple shaders and defines the semantics
and syntax of the names allowed in #include directives. It also
defines API mechanisms to define the named string backing a
#include.
这个扩展介绍 #include GLSL 指令允许在多个 shaders 中可以复用相同 shader 文本。
New Procedures and Functions - 新的函数
void NamedStringARB(enum type, int namelen, const char *name,
int stringlen, const char *string)
void DeleteNamedStringARB(int namelen, const char *name)
void CompileShaderIncludeARB(uint shader, sizei count,
const char *const *path,
const int *length)
boolean IsNamedStringARB(int namelen, const char *name)
void GetNamedStringARB(int namelen, const char *name,
sizei bufSize, int *stringlen,
char *string)
void GetNamedStringivARB(int namelen, const char *name,
enum pname, int *params)
NamedStringARB是将指定的 include 文件名的内容传入到 GLSL 的 virtual file system（虚拟文件系统）DeleteNamedStringARB在 GLSL 中的 virtual file system 中删除指定 include 文件名的映射的内容CompileShaderIncludeARB是在编译指定的 shader 对象的源码是需要提前编译 include 用到的文件名的内容（如果有多个 include 就需要调用多次）IsNamedStringARB判断一个文件名是否 GLSL virtual file system 中已经映射好的内容GetNamedStringARB获取已经映射过的 include 文件名内容GetNamedStringivARB获取多个映射过的 include 文件名内容
New Tokens - 新的 Tokens 标记
Accepted by the <type> parameter of NamedStringARB:
SHADER_INCLUDE_ARB 0x8DAE
Accepted by the <pname> parameter of GetNamedStringivARB:
NAMED_STRING_LENGTH_ARB 0x8DE9
NAMED_STRING_TYPE_ARB 0x8DEA
2.11.1 - NamedStringARB 函数
Arbitrary strings may be defined and given names. These strings can
be included by name in shaders during compilation, allowing reuse of
the same code segments. A string and its name are specified
with the command
给指定的字符串定义一个名字。这些字符串可以在 shaders 编辑期间通过名字来 include，以此来允许复用相同的代码段。对应的命令为：
void NamedStringARB(enum type, int namelen, const char *name,
int stringlen, const char *string)
<type> must be SHADER_INCLUDE_ARB. <namelen> is the number of
<char>s in <name>. <name> defines the name associated with the
string. <stringlen> is the number of <char>s in <string>. <string>
is an arbitrary string of characters. If <namelen> or <stringlen>
are negative, then <name> or <string> respectively are considered to
be null-terminated strings.
type 必须为 SHADER_INCLUDE_ARB。namelen 是 name 字符串的长度。name 定义了名字对应的字符串。stringlen 是 string 字符串的长度。string 是对应的字符内容（也就是我们的 include 文件的内容）。如果 namelen 或是 stringlen 都是负数，那么 name 与 string 分别都认为是带有 null 结尾符的字符串。
<name> must be a <valid pathname> as defined in Appendix A of the
OpenGL Shading Language Specification. Additionally, <name> must
begin with the character '/'. Before creating a named string, <name>
is converted to a <tree location> as described in Appendix A of
the OpenGL Shading Language Specification.
name 必须是有一个 有效的路径名字，要遵从 OpenGL Shading Language Specification 规范。另外 name 必须要是字符 '/' 开头。在创建一个名字字符(name string)内容前,name 会被转换为一个遵从 OpenGL Shading Language Specification 规范的 tree location 树形结构定位。
After calling NamedStringARB, the contents of <string> are
associated with the tree location corresponding to <name>[fn1]. If a
string is already associated with that tree location, it will be
replaced with the new <string>.
在调用了 NamedStringARB 后， string 的内容以 name [fn1（脚注 foot note 1）] 对应定位在树形结构中。如果一个字符串（这里貌似有笔误，应该是 name 名字）内容已经存在树形定位中，那么将会以新的 string 内容替换。
[fn1 - Many possible <name>s may correspond to the same tree
location.]
【fn1（脚注1） - 许多的 name(s) 名字可能会对应着同一个树形结构定位中。】
An INVALID_VALUE error will be generated under any of the following
conditions:
- Either <name> or <string> is NULL.
- <name> is not a valid pathname beginning with '/'.
以下的条件将会生成 INVALID_VALUE 错误：
name和stirng都是NULL。name不是有效的路径名字，没有以'/'开头
DeleteNamedStringARB 函数
To delete a named string, use the command
void DeleteNamedStringARB(int namelen, const char *name)
<namelen>, and <name> have the same meanings as the corresponding
parameters of NamedStringARB. After calling DeleteNamedStringARB, no
string is associated with the tree location corresponding to <name>.
An INVALID_VALUE error will be generated under any of the following
conditions:
- <name> is NULL.
- <name> is not a valid pathname beginning with '/'.
An INVALID_OPERATION error will be generated if the tree location
corresponding to <name> has no string associated with it."
删除一个 name string 名字字符串，使用命令：
void DeleteNamedStringARB(int namelen, const char *name)
namelen 和 name 和 NameStringARB 函数中有着一样的意思。在调用了 DeleteNamedStringARB ，将不会有对应的 name 对应的字符串内容存在与树形结构定位中。
以下条件将会生成 INVALID_VALUE 错误：
name为NULL。name不是一个以'/'开头的有效路径名字
如果树形结构定位中没有对应的 name 对应的字符内容，则生成 INVALID_OPERATION 错误。
CompileShaderIncludeARB 函数
在新的 2.11.2 小节中替代了 CompileShader 的描述：
"Once the source code for a shader has been loaded, a shader object
can be compiled with the command"
“一旦 shader 代码加载好了，那么 shader 对象就可以使用以下命令来编译”
void CompileShaderIncludeARB(uint shader, sizei count,
const char * const *path,
const int *length)
<path> is an ordered array of <count> pointers to optionally
null-terminated character strings defining <search paths>. <length>
is an array of <count> values with the number of chars in each
string (the string length). If an element in <length> is negative,
its accompanying string is null-terminated. If <length> is NULL, all
strings in the <path> argument are considered null-terminated.
path 是 count 个有序数组的指针，并且可选的 null 结尾符，字符内定义着 search paths （include 的搜索路径）。length 是 count 个数组中，每个 path 中对应的长度。如果 length 中某个元素为负数，则对应的 path 内的字符串以 null' 字符结尾。如果 length 为 NULL，那么所有 path 的字符串都以 null 字符结尾。
Each string in <path> must be a valid <pathname> as defined in
Appendix A of the OpenGL Shading Language Specification, and must
begin with the character '/'. The ordered list of <path>s is used
during compilation, together with the arguments of #include
directives in the shader source, to search for named strings
corresponding to the #include directives as described in section
3.3 of the OpenGL Shading Language Specification. If a #include
directive does not correspond to a valid named string, compilation
will fail.
每个 path 里的字符串必须是一个有效的 pathname 路径名字，并且必须以 '/' 字符开头。有序 path(s) 列表用于编译期间，和带有 #include 指令的 shader 源码一起，来完成对 include 名字的字符串内容搜索。如果 #include 指令没有一个对应有效的 named string 名字字符串，那么编译失败。
Each shader object has a boolean status that is modified as a result
of compilation, and can be queried by calling GetShaderiv (see
section 6.1.10) with <pname> COMPILE_STATUS. The status will be set
to TRUE if <shader> was compiled without errors and is ready for
use, and FALSE otherwise. Compilation can fail for a variety of
reasons as listed in the OpenGL Shading Language Specification. If
compilation failed, any information about a previous compile is
lost. Thus a failed compile does not restore the old state of
shader.
每个 shader 对象都有一个可修改的 boolean 状态来表示编译结果，并且可以通过调用 GetShaderiv （查看 6.1.10 小节）函数，带上 COMPILE_STATUS 来查询编译结果。如果 shader 编译没有错误，那么 shader 的编译状态为 TRUE，并可就绪使用，否则编译状态为 FALSE。因为 OpenGL Shading Language Specification 规范的原因可能 shader 编译都会有错误。如果编译失败，任何相关之前编译的信息都将会丢失。因为编译使用将会恢复 shader 的旧状态。
Changing the source code of a shader object with ShaderSource, or
the contents of any named strings corresponding to #include
directives in the source code, does not change its compile status or
the compiled shader code.
使用 ShaderSource 修改 shader 对象的的源码，偶是 shader 中 #include 命令包含的源码修改了，都不会改变该 shader 代码的编译状态。（因为改了代码后，要重新执行编译才会修改 shader 的编译状态）
Each shader object has an information log, which is a text string
that is overwritten as a result of compilation. This information log
can be queried with GetShaderInfoLog to obtain more information
about the compilation attempt (see section 6.1.10).
每个 shader 对象都有一个日志信息，它是在编译后输入的一个编译结果字符信息。这个日志信息可以使用 GetShaderInfoLog 来获取更多的相关编译的附加信息（查看 6.1.10 小节）。
An INVALID_OPERATION error is generated if <shader> is not the name
of a valid shader object generated by CreateShader.
如果 shader 不是一个通过 CreateShader 创建的有效的 shader 对象，那么将生成 INVALID_OPERATION 错误。
An INVALID_VALUE error will be generated under any of the following
conditions:
- <count> is greater than zero and <path> is NULL, or any
of the pointers path[0] .. path[<count>-1] is NULL.
- Any of the strings in <path> are not valid pathnames beginning
with '/'.
以下条件将会生成 INVALID_VALUE 错误：
count大于 0， 并且path是NULL，或是任意的path[0]指针 …path[count-1]为NULL。- 任意的
path字符串内容不是一个以'/'的有效的路径名字的。
*** (compatibility profile only)
An INVALID_OPERATION error is generated if CompileShaderIncludeARB
is executed between Begin and the corresponding End.
The command
CompileShader(uint shader)
is equivalent to
CompileShaderIncludeARB(shader,0,NULL,NULL).
Shader objects can be deleted with the command ..."
(compatibility profile only，仅仅在 profile 为 compatibility中)
如果 CompileShaderIncludeARB 在 Begin 和 End 之间调用，则会产生一个 INVALID_OPERATION 错误。
命令：
CompileShader(uint shader)
等价于
CompileShaderIncludeARB(shader,0,NULL,NULL).
6.1.10 - IsNamedStringARB 函数
Named String Queries - 名字字符串查询
The command
boolean IsNamedStringARB(int namelen, const char *name)
returns TRUE if the tree location corresponding to <name> has a
string associated with it, and FALSE if the tree location has no
string associated with it. <name> and <namelen> have the same
meanings as the corresponding parameters of NamedStringARB (see
section 2.11.1).
命令：
boolean IsNamedStringARB(int namelen, const char *name)
如果对应的 name 树形结构中存有，则返回 TRUE，如果对应的 name 没有，则返回 FALSE。name 和 namelen 都是与 NamedStringARB 函数的参数中一样的意思（查看 2.11.1 小节）
如果 name 和 namelen 描述的不是一个有效的名字，或是 name 为 NULL，IsNamedStringARB 函数返回 FALSE。
GetNamedStringivARB 函数
The command
void GetNamedStringivARB(int namelen, const char *name,
enum pname, int *params)
returns properties of the named string whose tree location
corresponds to <name>. <name> and <namelen> have the same meanings
as the corresponding parameters of NamedStringARB (see section
2.11.1). The parameter value to return is specified by <pname>.
If <pname> is NAMED_STRING_LENGTH_ARB, the length of the named
string, including a null terminator, is returned. If <pname> is
NAMED_STRING_TYPE_ARB, the <type> argument passed to NamedStringARB
is returned.
命令：
void GetNamedStringivARB(int namelen, const char *name,
enum pname, int *params)
返回对应树形结构定位中的 name 对应的 named string 名字字符串的属性。name 和 namelen 于 NamedStringARB 函数的参数中一样的意思（查看 2.11.1 小节）。返回的属性是对应 pname 对应的属性。
如果 pname 是 NAMED_STRING_LENGTH_ARB ，则返回null 结尾符的 named string 名字字符串的长度。如果 pname 是 NAMED_STRING_TYPE_ARB ，则传入函数 NamedStringARB 的参数 type 的值将被返回。
An INVALID_VALUE error will be generated under any of the following
conditions:
- <name> is NULL.
- <name> is not a valid pathname beginning with '/'.
An INVALID_OPERATION error will be generated if the tree location
corresponding to <name> has no string associated with it.
以下条件将会产生一个 INVALID_VALUE 错误：
name为NULL。name不是一个以'/'字符开头的有效的路径名字。
如果树形结构中没有 name 对应的字符串内容，将产生一个 INVALID_OPERATION 错误。
GetNamedStringARB 函数
The command
void GetNamedStringARB(int namelen, const char *name,
sizei bufSize, int *stringlen,
char *string)
returns in <string> the string corresponding to the specified
<name>. <name> and <namelen> have the same meanings as the
corresponding parameters of NamedStringARB.
The returned string will be null-terminated. The actual number of
characters written into <string>, excluding the null terminator, is
returned in <stringlen>. If <stringlen> is NULL, no length is
returned. The maximum number of characters that may be written into
<string>, including the null terminator, is specified by <bufSize>.
An INVALID_VALUE error will be generated under any of the following
conditions:
- <name> is NULL.
- <name> is not a valid pathname beginning with '/'.
An INVALID_OPERATION error will be generated if the tree location
corresponding to <name> has no string associated with it."
命令：
void GetNamedStringARB(int namelen, const char *name,
sizei bufSize, int *stringlen,
char *string)
返回指定 name 对应的 string 字符串的内容。 name 和 namelen 与 NamedStringARB 函数中的参数一样的意思。
返回的字符串将会以 null 结尾符结尾。已经写入的 string 字符串内容，并不包含 null 结尾符，返回的是 stringlen 长度的字符串。如果 stringlen 为 NULL，将不会返回带有长度的内容。最大的写入 string 的字符数量，包含了 null 结尾符，都是通过 buffSize 参数指定。
以下条件产生一个 INVALID_VALUE 错误：
name为NULL。name不是一个'/'字符开头的有效的路径名字。
如果对应的 name 在树形结构定位中不存在，则产生一个 INVALID_OPERATION 错误。
OK，API 翻译介绍就到这里，还有其他的一些 说明、问题，可以查看 extensions/ARB/ARB_shading_language_include.txt。
使用
此篇：LearnGL - 12 - GLSL include - GL_ARB_shading_language_include (Extensions扩展) - 各种踩坑，主要使用了 NamedStringARB API 实现 GLSL include 的功能
扫一扫
2953
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
