1 <?xml version=
"1.0" encoding=
"UTF-8"?>
2 <!DOCTYPE book PUBLIC
"-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
3 "http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
4 <refentry id=
"glPrioritizeTextures">
9 <holder>Silicon Graphics, Inc.
</holder>
12 <refentrytitle>glPrioritizeTextures
</refentrytitle>
13 <manvolnum>3G
</manvolnum>
16 <refname>glPrioritizeTextures
</refname>
17 <refpurpose>set texture residence priority
</refpurpose>
19 <refsynopsisdiv><title>C Specification
</title>
22 <funcdef>void
<function>glPrioritizeTextures
</function></funcdef>
23 <paramdef>GLsizei
<parameter>n
</parameter></paramdef>
24 <paramdef>const GLuint *
<parameter>textures
</parameter></paramdef>
25 <paramdef>const GLclampf *
<parameter>priorities
</parameter></paramdef>
29 <refsect1 id=
"parameters"><title>Parameters
</title>
32 <term><parameter>n
</parameter></term>
35 Specifies the number of textures to be prioritized.
40 <term><parameter>textures
</parameter></term>
43 Specifies an array containing the names of the textures to be prioritized.
48 <term><parameter>priorities
</parameter></term>
51 Specifies an array containing the texture priorities.
52 A priority given in an element of
<parameter>priorities
</parameter> applies to the texture
53 named by the corresponding element of
<parameter>textures
</parameter>.
59 <refsect1 id=
"description"><title>Description
</title>
61 <function>glPrioritizeTextures
</function> assigns the
<parameter>n
</parameter> texture priorities given in
<parameter>priorities
</parameter> to the
62 <parameter>n
</parameter> textures named in
<parameter>textures
</parameter>.
66 a ``working set'' of textures that are resident in texture memory.
67 These textures may be bound to a texture target much more efficiently
68 than textures that are not resident.
69 By specifying a priority for each texture,
70 <function>glPrioritizeTextures
</function> allows applications to guide the GL implementation in determining
71 which textures should be resident.
74 The priorities given in
<parameter>priorities
</parameter> are clamped to the range
75 <inlineequation><mml:math>
77 <mml:mfenced open=
"[" close=
"]">
81 </mml:math></inlineequation>
82 before they are assigned.
83 0 indicates the lowest priority; textures with priority
0
84 are least likely to be resident.
85 1 indicates the highest priority; textures with priority
1
86 are most likely to be resident.
87 However, textures are not guaranteed to be resident until they are used.
90 <function>glPrioritizeTextures
</function> silently ignores attempts to prioritize texture
0 or any texture
91 name that does not correspond to an existing texture.
94 <function>glPrioritizeTextures
</function> does not require that any of the textures named by
<parameter>textures
</parameter>
95 be bound to a texture target.
96 <citerefentry><refentrytitle>glTexParameter
</refentrytitle></citerefentry> may also be used to set a texture's priority,
97 but only if the texture is currently bound.
98 This is the only way to set the priority of a default texture.
101 <refsect1 id=
"notes"><title>Notes
</title>
103 <function>glPrioritizeTextures
</function> is available only if the GL version is
1.1 or greater.
106 <refsect1 id=
"errors"><title>Errors
</title>
108 <constant>GL_INVALID_VALUE
</constant> is generated if
<parameter>n
</parameter> is negative.
111 <constant>GL_INVALID_OPERATION
</constant> is generated if
<function>glPrioritizeTextures
</function> is executed
112 between the execution of
<citerefentry><refentrytitle>glBegin
</refentrytitle></citerefentry> and the corresponding
113 execution of
<citerefentry><refentrytitle>glEnd
</refentrytitle></citerefentry>.
116 <refsect1 id=
"associatedgets"><title>Associated Gets
</title>
118 <citerefentry><refentrytitle>glGetTexParameter
</refentrytitle></citerefentry> with parameter name
<constant>GL_TEXTURE_PRIORITY
</constant>
119 retrieves the priority of a currently bound texture.
122 <refsect1 id=
"seealso"><title>See Also
</title>
124 <citerefentry><refentrytitle>glAreTexturesResident
</refentrytitle></citerefentry>,
125 <citerefentry><refentrytitle>glBindTexture
</refentrytitle></citerefentry>,
126 <citerefentry><refentrytitle>glCopyTexImage1D
</refentrytitle></citerefentry>,
127 <citerefentry><refentrytitle>glCopyTexImage2D
</refentrytitle></citerefentry>,
128 <citerefentry><refentrytitle>glTexImage1D
</refentrytitle></citerefentry>,
129 <citerefentry><refentrytitle>glTexImage2D
</refentrytitle></citerefentry>,
130 <citerefentry><refentrytitle>glTexImage3D
</refentrytitle></citerefentry>,
131 <citerefentry><refentrytitle>glTexParameter
</refentrytitle></citerefentry>
134 <refsect1 id=
"Copyright"><title>Copyright
</title>
136 Copyright
<trademark class=
"copyright"></trademark> 1991-
2006
137 Silicon Graphics, Inc. This document is licensed under the SGI
138 Free Software B License. For details, see
139 <ulink url=
"http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/
</ulink>.