upstream-man-pages/man2/glConvolutionParameter.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="glConvolutionParameter">
   5     <refmeta>
   6         <refmetainfo>
   7             <copyright>
   8                 <year>1991-2006</year>
   9                 <holder>Silicon Graphics, Inc.</holder>
  10             </copyright>
  11         </refmetainfo>
  12         <refentrytitle>glConvolutionParameter</refentrytitle>
  13         <manvolnum>3G</manvolnum>
  14     </refmeta>
  15     <refnamediv>
  16         <refname>glConvolutionParameter</refname>
  17         <refpurpose>set convolution parameters</refpurpose>
  18     </refnamediv>
  19     <refsynopsisdiv><title>C Specification</title>
  20         <funcsynopsis>
  21             <funcprototype>
  22                 <funcdef>void <function>glConvolutionParameterf</function></funcdef>
  23                 <paramdef>GLenum <parameter>target</parameter></paramdef>
  24                 <paramdef>GLenum <parameter>pname</parameter></paramdef>
  25                 <paramdef>GLfloat <parameter>params</parameter></paramdef>
  26             </funcprototype>
  27         </funcsynopsis>
  28         <funcsynopsis>
  29             <funcprototype>
  30                 <funcdef>void <function>glConvolutionParameteri</function></funcdef>
  31                 <paramdef>GLenum <parameter>target</parameter></paramdef>
  32                 <paramdef>GLenum <parameter>pname</parameter></paramdef>
  33                 <paramdef>GLint <parameter>params</parameter></paramdef>
  34             </funcprototype>
  35         </funcsynopsis>
  36     </refsynopsisdiv>
  37     <!-- eqn: ignoring delim $$ -->
  38     <para>
  39     </para>
  40     <refsect1 id="parameters"><title>Parameters</title>
  41         <variablelist>
  42         <varlistentry>
  43             <term><parameter>target</parameter></term>
  44             <listitem>
  45                 <para>
  46                     The target for the convolution parameter.
  47                     Must be one of
  48                     <constant>GL_CONVOLUTION_1D</constant>,
  49                     <constant>GL_CONVOLUTION_2D</constant>, or
  50                     <constant>GL_SEPARABLE_2D</constant>.
  51                 </para>
  52             </listitem>
  53         </varlistentry>
  54         <varlistentry>
  55             <term><parameter>pname</parameter></term>
  56             <listitem>
  57                 <para>
  58                     The parameter to be set.
  59                     Must be
  60                     <constant>GL_CONVOLUTION_BORDER_MODE</constant>.
  61                 </para>
  62             </listitem>
  63         </varlistentry>
  64         <varlistentry>
  65             <term><parameter>params</parameter></term>
  66             <listitem>
  67                 <para>
  68                     The parameter value.
  69                     Must be one of
  70                     <constant>GL_REDUCE</constant>, <constant>GL_CONSTANT_BORDER</constant>, <constant>GL_REPLICATE_BORDER</constant>.
  71                 </para>
  72                 <para>
  73                 </para>
  74             </listitem>
  75         </varlistentry>
  76         </variablelist>
  77     </refsect1>
  78     <refsynopsisdiv><title>C Specification</title>
  79         <funcsynopsis>
  80             <funcprototype>
  81                 <funcdef>void <function>glConvolutionParameterfv</function></funcdef>
  82                 <paramdef>GLenum <parameter>target</parameter></paramdef>
  83                 <paramdef>GLenum <parameter>pname</parameter></paramdef>
  84                 <paramdef>const GLfloat * <parameter>params</parameter></paramdef>
  85             </funcprototype>
  86         </funcsynopsis>
  87         <funcsynopsis>
  88             <funcprototype>
  89                 <funcdef>void <function>glConvolutionParameteriv</function></funcdef>
  90                 <paramdef>GLenum <parameter>target</parameter></paramdef>
  91                 <paramdef>GLenum <parameter>pname</parameter></paramdef>
  92                 <paramdef>const GLint * <parameter>params</parameter></paramdef>
  93             </funcprototype>
  94         </funcsynopsis>
  95     </refsynopsisdiv>
  96     <para>
  97     </para>
  98     <refsect1 id="parameters2"><title>Parameters</title>
  99         <variablelist>
 100         <varlistentry>
 101             <term><parameter>target</parameter></term>
 102             <listitem>
 103                 <para>
 104                     The target for the convolution parameter.
 105                     Must be one of
 106                     <constant>GL_CONVOLUTION_1D</constant>,
 107                     <constant>GL_CONVOLUTION_2D</constant>, or
 108                     <constant>GL_SEPARABLE_2D</constant>.
 109                 </para>
 110             </listitem>
 111         </varlistentry>
 112         <varlistentry>
 113             <term><parameter>pname</parameter></term>
 114             <listitem>
 115                 <para>
 116                     The parameter to be set.
 117                     Must be one of
 118                     <constant>GL_CONVOLUTION_BORDER_MODE</constant>,
 119                     <constant>GL_CONVOLUTION_BORDER_COLOR</constant>,
 120                     <constant>GL_CONVOLUTION_FILTER_SCALE</constant>, or
 121                     <constant>GL_CONVOLUTION_FILTER_BIAS</constant>.
 122                 </para>
 123             </listitem>
 124         </varlistentry>
 125         <varlistentry>
 126             <term><parameter>params</parameter></term>
 127             <listitem>
 128                 <para>
 129                     The parameter value.
 130                     If <parameter>pname</parameter>v is <constant>GL_CONVOLUTION_BORDER_MODE</constant>, <parameter>params</parameter>v must be one of
 131                     <constant>GL_REDUCE</constant>, <constant>GL_CONSTANT_BORDER</constant>, or <constant>GL_REPLICATE_BORDER</constant>.
 132                     Otherwise, must be a vector of four values (for red, green, blue, and alpha,
 133                     respectively) to be used for
 134                     scaling (when <parameter>pname</parameter>v is <constant>GL_CONVOLUTION_FILTER_SCALE</constant>), or
 135                     biasing (when <parameter>pname</parameter>v is <constant>GL_CONVOLUTION_FILTER_BIAS</constant>) a convolution
 136                     filter kernel or setting the constant border color (when <parameter>pname</parameter>v is
 137                     <constant>GL_CONVOLUTION_BORDER_COLOR</constant>.
 138                 </para>
 139             </listitem>
 140         </varlistentry>
 141         </variablelist>
 142     </refsect1>
 143     <refsect1 id="description"><title>Description</title>
 144         <para>
 145             <function>glConvolutionParameter</function> sets the value of a convolution parameter.
 146         </para>
 147         <para>
 148             <parameter>target</parameter> selects the convolution filter to be affected:
 149             <constant>GL_CONVOLUTION_1D</constant>,
 150             <constant>GL_CONVOLUTION_2D</constant>, or
 151             <constant>GL_SEPARABLE_2D</constant>
 152             for the 1D, 2D, or separable 2D filter, respectively.
 153         </para>
 154         <para>
 155             <parameter>pname</parameter> selects the parameter to be changed.
 156             <constant>GL_CONVOLUTION_FILTER_SCALE</constant> and <constant>GL_CONVOLUTION_FILTER_BIAS</constant>
 157             affect the definition of the convolution filter kernel; see
 158             <citerefentry><refentrytitle>glConvolutionFilter1D</refentrytitle></citerefentry>, <citerefentry><refentrytitle>glConvolutionFilter2D</refentrytitle></citerefentry>, and
 159             <citerefentry><refentrytitle>glSeparableFilter2D</refentrytitle></citerefentry> for details.
 160             In these cases, <parameter>params</parameter>v is an array of four values to be applied to
 161             red, green, blue, and alpha values, respectively. The initial value for
 162             <constant>GL_CONVOLUTION_FILTER_SCALE</constant> is (1, 1, 1, 1), and the initial value
 163             for <constant>GL_CONVOLUTION_FILTER_BIAS</constant> is (0, 0, 0, 0).
 164         </para>
 165         <para>
 166             A <parameter>pname</parameter> value of <constant>GL_CONVOLUTION_BORDER_MODE</constant> controls the
 167             convolution border mode. The accepted modes are:
 168         </para>
 169         <variablelist>
 170             <varlistentry>
 171                 <term><constant>GL_REDUCE</constant></term>
 172                 <listitem>
 173                     <para>
 174                         The image resulting from convolution is
 175                         smaller than the source image.
 176                         If the filter width is
 177                         <inlineequation><mml:math><mml:mi mathvariant="italic">Wf</mml:mi></mml:math></inlineequation>
 178                         and height is
 179                         <inlineequation><mml:math><mml:mi mathvariant="italic">Hf</mml:mi></mml:math></inlineequation>,
 180                         and the source image width is
 181                         <inlineequation><mml:math><mml:mi mathvariant="italic">Ws</mml:mi></mml:math></inlineequation>
 182                         and height is
 183                         <inlineequation><mml:math><mml:mi mathvariant="italic">Hs</mml:mi></mml:math></inlineequation>,
 184                         then the convolved image width will be
 185                         <inlineequation><mml:math>
 186                             <!-- eqn: Ws  -  Wf  +  1:-->
 187                             <mml:mrow>
 188                                 <mml:mi mathvariant="italic">Ws</mml:mi>
 189                                 <mml:mo>-</mml:mo>
 190                                 <mml:mi mathvariant="italic">Wf</mml:mi>
 191                                 <mml:mo>+</mml:mo>
 192                                 <mml:mn>1</mml:mn>
 193                             </mml:mrow>
 194                         </mml:math></inlineequation>
 195                         and height
 196                         will be
 197                         <inlineequation><mml:math>
 198                             <!-- eqn: Hs  -  Hf  +  1:-->
 199                             <mml:mrow>
 200                                 <mml:mi mathvariant="italic">Hs</mml:mi>
 201                                 <mml:mo>-</mml:mo>
 202                                 <mml:mi mathvariant="italic">Hf</mml:mi>
 203                                 <mml:mo>+</mml:mo>
 204                                 <mml:mn>1</mml:mn>
 205                             </mml:mrow>
 206                         </mml:math></inlineequation>.
 207                         (If this reduction would generate an image with zero or negative width
 208                         and/or height, the output is simply null, with no error generated.)
 209                         The coordinates of the image resulting from convolution are zero
 210                         through
 211                         <inlineequation><mml:math>
 212                             <!-- eqn: Ws  -  Wf:-->
 213                             <mml:mrow>
 214                                 <mml:mi mathvariant="italic">Ws</mml:mi>
 215                                 <mml:mo>-</mml:mo>
 216                                 <mml:mi mathvariant="italic">Wf</mml:mi>
 217                             </mml:mrow>
 218                         </mml:math></inlineequation>
 219                         in width and zero through
 220                         <inlineequation><mml:math>
 221                             <!-- eqn: Hs  -  Hf:-->
 222                             <mml:mrow>
 223                                 <mml:mi mathvariant="italic">Hs</mml:mi>
 224                                 <mml:mo>-</mml:mo>
 225                                 <mml:mi mathvariant="italic">Hf</mml:mi>
 226                             </mml:mrow>
 227                         </mml:math></inlineequation>
 228                         in
 229                         height.
 230                     </para>
 231                 </listitem>
 232             </varlistentry>
 233             <varlistentry>
 234                 <term><constant>GL_CONSTANT_BORDER</constant></term>
 235                 <listitem>
 236                     <para>
 237                         The image resulting from convolution is the same size as the source image, and
 238                         processed as if the source image were surrounded by pixels with their color
 239                         specified by the <constant>GL_CONVOLUTION_BORDER_COLOR</constant>.
 240                     </para>
 241                 </listitem>
 242             </varlistentry>
 243             <varlistentry>
 244                 <term><constant>GL_REPLICATE_BORDER</constant></term>
 245                 <listitem>
 246                     <para>
 247                         The image resulting from convolution is the same size as the source image, and
 248                         processed as if the outermost pixel on the border of the source image were
 249                         replicated.
 250                     </para>
 251                 </listitem>
 252             </varlistentry>
 253         </variablelist>
 254     </refsect1>
 255     <refsect1 id="notes"><title>Notes</title>
 256         <para>
 257             <function>glConvolutionParameter</function> is present only if <code>ARB_imaging</code> is returned when <citerefentry><refentrytitle>glGetString</refentrytitle></citerefentry>
 258             is called with an argument of <constant>GL_EXTENSIONS</constant>.
 259         </para>
 260         <para>
 261             In cases where errors can result from the specification of invalid
 262             image dimensions, it is the dimensions after convolution that are
 263             tested, not the dimensions of the source image.
 264             For example, <citerefentry><refentrytitle>glTexImage1D</refentrytitle></citerefentry> requires power-of-two image size.
 265             When <constant>GL_REDUCE</constant> border mode is in effect,
 266             the source image must be larger than the final power-of-two size
 267             by one less than the size of the 1D filter kernel.
 268         </para>
 269     </refsect1>
 270     <refsect1 id="errors"><title>Errors</title>
 271         <para>
 272             <constant>GL_INVALID_ENUM</constant> is generated if <parameter>target</parameter> is not one of the allowable
 273             values.
 274         </para>
 275         <para>
 276             <constant>GL_INVALID_ENUM</constant> is generated if <parameter>pname</parameter> is not one of the allowable
 277             values.
 278         </para>
 279         <para>
 280             <constant>GL_INVALID_ENUM</constant> is generated if <parameter>pname</parameter> is
 281             <constant>GL_CONVOLUTION_BORDER_MODE</constant> and <parameter>params</parameter> is not one of
 282             <constant>GL_REDUCE</constant>, <constant>GL_CONSTANT_BORDER</constant>, or <constant>GL_REPLICATE_BORDER</constant>.
 283         </para>
 284         <para>
 285             <constant>GL_INVALID_OPERATION</constant> is generated if <function>glConvolutionParameter</function> is executed
 286             between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry> and the corresponding
 287             execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
 288         </para>
 289     </refsect1>
 290     <refsect1 id="associatedgets"><title>Associated Gets</title>
 291         <para>
 292             <citerefentry><refentrytitle>glGetConvolutionParameter</refentrytitle></citerefentry>
 293         </para>
 294     </refsect1>
 295     <refsect1 id="seealso"><title>See Also</title>
 296         <para>
 297             <citerefentry><refentrytitle>glConvolutionFilter1D</refentrytitle></citerefentry>,
 298             <citerefentry><refentrytitle>glConvolutionFilter2D</refentrytitle></citerefentry>,
 299             <citerefentry><refentrytitle>glSeparableFilter2D</refentrytitle></citerefentry>,
 300             <citerefentry><refentrytitle>glGetConvolutionParameter</refentrytitle></citerefentry>
 301         </para>
 302     </refsect1>
 303     <refsect1 id="Copyright"><title>Copyright</title>
 304         <para>
 305             Copyright <trademark class="copyright"></trademark> 1991-2006
 306             Silicon Graphics, Inc. This document is licensed under the SGI
 307             Free Software B License. For details, see
 308             <ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
 309         </para>
 310     </refsect1>
 311 </refentry>