upstream-doc/manglsl/textureGrad.xml

   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="textureGrad">
   5     <refmeta>
   6         <refmetainfo>
   7             <copyright>
   8                 <year>2011</year>
   9                 <holder>Khronos Group</holder>
  10             </copyright>
  11         </refmetainfo>
  12         <refentrytitle>textureGrad</refentrytitle>
  13         <manvolnum>3G</manvolnum>
  14     </refmeta>
  15     <refnamediv>
  16         <refname>textureGrad</refname>
  17         <refpurpose>perform a texture lookup with explicit gradients</refpurpose>
  18     </refnamediv>
  19     <refsynopsisdiv><title>Declaration</title>
  20         <funcsynopsis>
  21             <funcprototype>
  22                 <funcdef>gvec4 <function>textureGrad</function></funcdef>
  23                 <paramdef>gsampler1D <parameter>sampler</parameter></paramdef>
  24                 <paramdef>float <parameter>P</parameter></paramdef>
  25                 <paramdef>float <parameter>dPdx</parameter></paramdef>
  26                 <paramdef>float <parameter>dPdy</parameter></paramdef>
  27             </funcprototype>
  28             <funcprototype>
  29                 <funcdef>gvec4 <function>textureGrad</function></funcdef>
  30                 <paramdef>gsampler2D <parameter>sampler</parameter></paramdef>
  31                 <paramdef>vec2 <parameter>P</parameter></paramdef>
  32                 <paramdef>vec2 <parameter>dPdx</parameter></paramdef>
  33                 <paramdef>vec2 <parameter>dPdy</parameter></paramdef>
  34             </funcprototype>
  35             <funcprototype>
  36                 <funcdef>gvec4 <function>textureGrad</function></funcdef>
  37                 <paramdef>gsampler3D <parameter>sampler</parameter></paramdef>
  38                 <paramdef>vec3 <parameter>P</parameter></paramdef>
  39                 <paramdef>vec3 <parameter>dPdx</parameter></paramdef>
  40                 <paramdef>vec3 <parameter>dPdy</parameter></paramdef>
  41             </funcprototype>
  42             <funcprototype>
  43                 <funcdef>gvec4 <function>textureGrad</function></funcdef>
  44                 <paramdef>gsamplerCube <parameter>sampler</parameter></paramdef>
  45                 <paramdef>vec3 <parameter>P</parameter></paramdef>
  46                 <paramdef>vec3 <parameter>dPdx</parameter></paramdef>
  47                 <paramdef>vec3 <parameter>dPdy</parameter></paramdef>
  48             </funcprototype>
  49             <funcprototype>
  50                 <funcdef>gvec4 <function>textureGrad</function></funcdef>
  51                 <paramdef>gsampler2DRect <parameter>sampler</parameter></paramdef>
  52                 <paramdef>vec2 <parameter>P</parameter></paramdef>
  53                 <paramdef>vec2 <parameter>dPdx</parameter></paramdef>
  54                 <paramdef>vec2 <parameter>dPdy</parameter></paramdef>
  55             </funcprototype>
  56             <funcprototype>
  57                 <funcdef>float <function>textureGrad</function></funcdef>
  58                 <paramdef>gsampler2DRectShadow <parameter>sampler</parameter></paramdef>
  59                 <paramdef>vec2 <parameter>P</parameter></paramdef>
  60                 <paramdef>vec2 <parameter>dPdx</parameter></paramdef>
  61                 <paramdef>vec2 <parameter>dPdy</parameter></paramdef>
  62             </funcprototype>
  63             <funcprototype>
  64                 <funcdef>float <function>textureGrad</function></funcdef>
  65                 <paramdef>sampler1DShadow <parameter>sampler</parameter></paramdef>
  66                 <paramdef>vec3 <parameter>P</parameter></paramdef>
  67                 <paramdef>float <parameter>dPdx</parameter></paramdef>
  68                 <paramdef>float <parameter>dPdy</parameter></paramdef>
  69             </funcprototype>
  70             <funcprototype>
  71                 <funcdef>float <function>textureGrad</function></funcdef>
  72                 <paramdef>sampler2DShadow <parameter>sampler</parameter></paramdef>
  73                 <paramdef>vec3 <parameter>P</parameter></paramdef>
  74                 <paramdef>vec2 <parameter>dPdx</parameter></paramdef>
  75                 <paramdef>vec2 <parameter>dPdy</parameter></paramdef>
  76             </funcprototype>
  77             <funcprototype>
  78                 <funcdef>gvec4 <function>textureGrad</function></funcdef>
  79                 <paramdef>gsampler1DArray <parameter>sampler</parameter></paramdef>
  80                 <paramdef>vec2 <parameter>P</parameter></paramdef>
  81                 <paramdef>float <parameter>dPdx</parameter></paramdef>
  82                 <paramdef>float <parameter>dPdy</parameter></paramdef>
  83             </funcprototype>
  84             <funcprototype>
  85                 <funcdef>gvec4 <function>textureGrad</function></funcdef>
  86                 <paramdef>gsampler2DArray <parameter>sampler</parameter></paramdef>
  87                 <paramdef>vec3 <parameter>P</parameter></paramdef>
  88                 <paramdef>vec2 <parameter>dPdx</parameter></paramdef>
  89                 <paramdef>vec2 <parameter>dPdy</parameter></paramdef>
  90             </funcprototype>
  91             <funcprototype>
  92                 <funcdef>float <function>textureGrad</function></funcdef>
  93                 <paramdef>sampler1DArrayShadow <parameter>sampler</parameter></paramdef>
  94                 <paramdef>vec3 <parameter>P</parameter></paramdef>
  95                 <paramdef>float <parameter>dPdx</parameter></paramdef>
  96                 <paramdef>float <parameter>dPdy</parameter></paramdef>
  97             </funcprototype>
  98             <funcprototype>
  99                 <funcdef>gvec4 <function>textureGrad</function></funcdef>
 100                 <paramdef>gsamplerCubeArray <parameter>sampler</parameter></paramdef>
 101                 <paramdef>vec4 <parameter>P</parameter></paramdef>
 102                 <paramdef>vec3 <parameter>dPdx</parameter></paramdef>
 103                 <paramdef>vec3 <parameter>dPdy</parameter></paramdef>
 104             </funcprototype>
 105         </funcsynopsis>
 106     </refsynopsisdiv>
 107     <refsect1 id="parameters"><title>Parameters</title>
 108         <variablelist>
 109         <varlistentry>
 110             <term><parameter>sampler</parameter></term>
 111             <listitem>
 112                 <para>
 113                     Specifies the sampler to which the texture from which texels will be retrieved is bound.
 114                 </para>
 115             </listitem>
 116         </varlistentry>
 117         <varlistentry>
 118             <term><parameter>P</parameter></term>
 119             <listitem>
 120                 <para>
 121                     Specifies the texture coordinates at which texture will be sampled.
 122                 </para>
 123             </listitem>
 124         </varlistentry>
 125         <varlistentry>
 126             <term><parameter>dPdx</parameter></term>
 127             <listitem>
 128                 <para>
 129                     Specifies the partial derivative of <parameter>P</parameter> with respect to window x.
 130                 </para>
 131             </listitem>
 132         </varlistentry>
 133         <varlistentry>
 134             <term><parameter>dPdy</parameter></term>
 135             <listitem>
 136                 <para>
 137                     Specifies the partial derivative of <parameter>P</parameter> with respect to window y.
 138                 </para>
 139             </listitem>
 140         </varlistentry>
 141         </variablelist>
 142     </refsect1>
 143     <refsect1 id="description"><title>Description</title>
 144         <para>
 145             <function>textureGrad</function> performs a texture lookup at coordinate <parameter>P</parameter> from the
 146             texture bound to <parameter>sampler</parameter> with explicit texture coordinate gradiends as specified in
 147             <parameter>dPdx</parameter> and <parameter>dPdy</parameter>. Set:
 148         </para>
 149         <para>
 150             <inlineequation><mml:math>
 151                 <mml:mfrac>
 152                   <mml:mi>&delta;s</mml:mi>
 153                   <mml:mi>&delta;x</mml:mi>
 154                 </mml:mfrac>
 155                 <mml:mo>=</mml:mo>
 156                 <mml:mfrac>
 157                   <mml:mi>&delta;P</mml:mi>
 158                   <mml:mi>&delta;x</mml:mi>
 159                 </mml:mfrac>
 160                 <mml:mi>&nbsp; for a 1D texture,&nbsp;  </mml:mi>
 161                 <mml:mfrac>
 162                   <mml:mi>&delta;P.s</mml:mi>
 163                   <mml:mi>&delta;x</mml:mi>
 164                 </mml:mfrac>
 165                 <mml:mi>&nbsp;  otherwise</mml:mi>
 166             </mml:math></inlineequation>
 167         </para>
 168         <para>
 169             <inlineequation><mml:math>
 170                 <mml:mfrac>
 171                   <mml:mi>&delta;s</mml:mi>
 172                   <mml:mi>&delta;y</mml:mi>
 173                 </mml:mfrac>
 174                 <mml:mo>=</mml:mo>
 175                 <mml:mfrac>
 176                   <mml:mi>&delta;P</mml:mi>
 177                   <mml:mi>&delta;y</mml:mi>
 178                 </mml:mfrac>
 179                 <mml:mi>&nbsp;  for a 1D texture,&nbsp; </mml:mi>
 180                 <mml:mfrac>
 181                   <mml:mi>&delta;P.s</mml:mi>
 182                   <mml:mi>&delta;y</mml:mi>
 183                 </mml:mfrac>
 184                 <mml:mi>&nbsp;  otherwise</mml:mi>
 185             </mml:math></inlineequation>
 186         </para>
 187         <para>
 188             <inlineequation><mml:math>
 189                 <mml:mfrac>
 190                   <mml:mi>&delta;t</mml:mi>
 191                   <mml:mi>&delta;x</mml:mi>
 192                 </mml:mfrac>
 193                 <mml:mo>=</mml:mo>
 194                 <mml:mn>0.0</mml:mn>
 195                 <mml:mi>&nbsp; for a 1D texture,&nbsp; </mml:mi>
 196                 <mml:mfrac>
 197                   <mml:mi>&delta;P.t</mml:mi>
 198                   <mml:mi>&delta;x</mml:mi>
 199                 </mml:mfrac>
 200                 <mml:mi> otherwise</mml:mi>
 201             </mml:math></inlineequation>
 202         </para>
 203         <para>
 204             <inlineequation><mml:math>
 205                 <mml:mfrac>
 206                   <mml:mi>&delta;t</mml:mi>
 207                   <mml:mi>&delta;y</mml:mi>
 208                 </mml:mfrac>
 209                 <mml:mo>=</mml:mo>
 210                 <mml:mn>0.0</mml:mn>
 211                 <mml:mi>&nbsp; for a 1D texture,&nbsp; </mml:mi>
 212                 <mml:mfrac>
 213                   <mml:mi>&delta;P.t</mml:mi>
 214                   <mml:mi>&delta;y</mml:mi>
 215                 </mml:mfrac>
 216                 <mml:mi>&nbsp; otherwise</mml:mi>
 217             </mml:math></inlineequation>
 218         </para>
 219         <para>
 220             <inlineequation><mml:math>
 221                 <mml:mfrac>
 222                   <mml:mi>&delta;r</mml:mi>
 223                   <mml:mi>&delta;x</mml:mi>
 224                 </mml:mfrac>
 225                 <mml:mo>=</mml:mo>
 226                 <mml:mn>0.0</mml:mn>
 227                 <mml:mi>&nbsp; for a 1D or 2D texture,&nbsp; </mml:mi>
 228                 <mml:mfrac>
 229                   <mml:mi>&delta;P.p</mml:mi>
 230                   <mml:mi>&delta;x</mml:mi>
 231                 </mml:mfrac>
 232                 <mml:mi>&nbsp; otherwise</mml:mi>
 233             </mml:math></inlineequation>
 234         </para>
 235         <para>
 236             <inlineequation><mml:math>
 237                 <mml:mfrac>
 238                   <mml:mi>&delta;r</mml:mi>
 239                   <mml:mi>&delta;y</mml:mi>
 240                 </mml:mfrac>
 241                 <mml:mo>=</mml:mo>
 242                 <mml:mn>0.0</mml:mn>
 243                 <mml:mi>&nbsp; for a 1D or 2D texture,&nbsp; </mml:mi>
 244                 <mml:mfrac>
 245                   <mml:mi>&delta;P.p</mml:mi>
 246                   <mml:mi>&delta;y</mml:mi>
 247                 </mml:mfrac>
 248                 <mml:mi>&nbsp; otherwise</mml:mi>
 249             </mml:math></inlineequation>
 250         </para>
 251         <para>
 252             For the cube version, the partial derivatives of <parameter>P</parameter> are assumed to be
 253             in the coordinate system used before texture coordinates are projected onto the appropriate
 254             cube face.
 255         </para>
 256     </refsect1>
 257     <refsect1 id="versions"><title>Version Support</title>
 258         <informaltable frame="topbot">
 259             #VARTABLECOLS#
 260                 <thead>
 261                     #FUNCTABLEHEADER#
 262                     <row>
 263                         <entry>textureGrad</entry>#newin13#
 264                     </row>
 265                     <row>
 266                         <entry>textureGrad (gsampler2DRect{Shadow})</entry>#newin14#
 267                     </row>
 268                     <row>
 269                         <entry>textureGrad (gsamplerCubeArray)</entry>#newin40#
 270                     </row>
 271                 </thead>
 272             </tgroup>
 273         </informaltable>
 274     </refsect1>
 275     <refsect1 id="seealso"><title>See Also</title>
 276         <para>
 277             <citerefentry><refentrytitle>texelFetch</refentrytitle></citerefentry>,
 278             <citerefentry><refentrytitle>texelFetchOffset</refentrytitle></citerefentry>,
 279             <citerefentry><refentrytitle>texture</refentrytitle></citerefentry>,
 280             <citerefentry><refentrytitle>textureGather</refentrytitle></citerefentry>,
 281             <citerefentry><refentrytitle>textureGatherOffset</refentrytitle></citerefentry>,
 282             <citerefentry><refentrytitle>textureGatherOffsets</refentrytitle></citerefentry>,
 283             <citerefentry><refentrytitle>textureGradOffset</refentrytitle></citerefentry>,
 284             <citerefentry><refentrytitle>textureLod</refentrytitle></citerefentry>,
 285             <citerefentry><refentrytitle>textureLodOffset</refentrytitle></citerefentry>,
 286             <citerefentry><refentrytitle>textureOffset</refentrytitle></citerefentry>,
 287             <citerefentry><refentrytitle>textureProj</refentrytitle></citerefentry>,
 288             <citerefentry><refentrytitle>textureProjGrad</refentrytitle></citerefentry>,
 289             <citerefentry><refentrytitle>textureProjGradOffset</refentrytitle></citerefentry>,
 290             <citerefentry><refentrytitle>textureProjLod</refentrytitle></citerefentry>,
 291             <citerefentry><refentrytitle>textureProjLodOffset</refentrytitle></citerefentry>,
 292             <citerefentry><refentrytitle>textureProjOffset</refentrytitle></citerefentry>,
 293             <citerefentry><refentrytitle>textureQueryLod</refentrytitle></citerefentry>,
 294             <citerefentry><refentrytitle>textureSize</refentrytitle></citerefentry>
 295         </para>
 296     </refsect1>
 297     <refsect1 id="Copyright"><title>Copyright</title>
 298         <para>
 299             Copyright <trademark class="copyright"></trademark> 2011 Khronos Group.
 300             This material may be distributed subject to the terms and conditions set forth in
 301             the Open Publication License, v 1.0, 8 June 1999.
 302             <ulink url="http://opencontent.org/openpub/">http://opencontent.org/openpub/</ulink>.
 303         </para>
 304     </refsect1>
 305 </refentry>