upstream-man-pages/man2/glGetConvolutionFilter.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="glGetConvolutionFilter">
   5     <refmeta>
   6         <refmetainfo>
   7             <copyright>
   8                 <year>1991-2006</year>
   9                 <holder>Silicon Graphics, Inc.</holder>
  10             </copyright>
  11         </refmetainfo>
  12         <refentrytitle>glGetConvolutionFilter</refentrytitle>
  13         <manvolnum>3G</manvolnum>
  14     </refmeta>
  15     <refnamediv>
  16         <refname>glGetConvolutionFilter</refname>
  17         <refpurpose>get current 1D or 2D convolution filter kernel</refpurpose>
  18     </refnamediv>
  19     <refsynopsisdiv><title>C Specification</title>
  20         <funcsynopsis>
  21             <funcprototype>
  22                 <funcdef>void <function>glGetConvolutionFilter</function></funcdef>
  23                 <paramdef>GLenum <parameter>target</parameter></paramdef>
  24                 <paramdef>GLenum <parameter>format</parameter></paramdef>
  25                 <paramdef>GLenum <parameter>type</parameter></paramdef>
  26                 <paramdef>GLvoid * <parameter>image</parameter></paramdef>
  27             </funcprototype>
  28         </funcsynopsis>
  29     </refsynopsisdiv>
  30     <refsect1 id="parameters"><title>Parameters</title>
  31         <variablelist>
  32         <varlistentry>
  33             <term><parameter>target</parameter></term>
  34             <listitem>
  35                 <para>
  36                     The filter to be retrieved.
  37                     Must be one of
  38                     <constant>GL_CONVOLUTION_1D</constant> or
  39                     <constant>GL_CONVOLUTION_2D</constant>.
  40                 </para>
  41             </listitem>
  42         </varlistentry>
  43         <varlistentry>
  44             <term><parameter>format</parameter></term>
  45             <listitem>
  46                 <para>
  47                     Format of the output image.
  48                     Must be one of
  49                     <constant>GL_RED</constant>,
  50                     <constant>GL_GREEN</constant>,
  51                     <constant>GL_BLUE</constant>,
  52                     <constant>GL_ALPHA</constant>,
  53                     <constant>GL_RGB</constant>,
  54                     <constant>GL_BGR</constant>,
  55                     <constant>GL_RGBA</constant>,
  56                     <constant>GL_BGRA</constant>,
  57                     <constant>GL_LUMINANCE</constant>, or
  58                     <constant>GL_LUMINANCE_ALPHA</constant>.
  59                 </para>
  60             </listitem>
  61         </varlistentry>
  62         <varlistentry>
  63             <term><parameter>type</parameter></term>
  64             <listitem>
  65                 <para>
  66                     Data type of components in the output image.
  67                     Symbolic constants
  68                     <constant>GL_UNSIGNED_BYTE</constant>,
  69                     <constant>GL_BYTE</constant>,
  70                     <constant>GL_BITMAP</constant>,
  71                     <constant>GL_UNSIGNED_SHORT</constant>,
  72                     <constant>GL_SHORT</constant>,
  73                     <constant>GL_UNSIGNED_INT</constant>,
  74                     <constant>GL_INT</constant>,
  75                     <constant>GL_FLOAT</constant>,
  76                     <constant>GL_UNSIGNED_BYTE_3_3_2</constant>,
  77                     <constant>GL_UNSIGNED_BYTE_2_3_3_REV</constant>,
  78                     <constant>GL_UNSIGNED_SHORT_5_6_5</constant>,
  79                     <constant>GL_UNSIGNED_SHORT_5_6_5_REV</constant>,
  80                     <constant>GL_UNSIGNED_SHORT_4_4_4_4</constant>,
  81                     <constant>GL_UNSIGNED_SHORT_4_4_4_4_REV</constant>,
  82                     <constant>GL_UNSIGNED_SHORT_5_5_5_1</constant>,
  83                     <constant>GL_UNSIGNED_SHORT_1_5_5_5_REV</constant>,
  84                     <constant>GL_UNSIGNED_INT_8_8_8_8</constant>,
  85                     <constant>GL_UNSIGNED_INT_8_8_8_8_REV</constant>,
  86                     <constant>GL_UNSIGNED_INT_10_10_10_2</constant>, and
  87                     <constant>GL_UNSIGNED_INT_2_10_10_10_REV</constant>
  88                     are accepted.
  89                 </para>
  90             </listitem>
  91         </varlistentry>
  92         <varlistentry>
  93             <term><parameter>image</parameter></term>
  94             <listitem>
  95                 <para>
  96                     Pointer to storage for the output image.
  97                 </para>
  98             </listitem>
  99         </varlistentry>
 100         </variablelist>
 101     </refsect1>
 102     <refsect1 id="description"><title>Description</title>
 103         <para>
 104             <function>glGetConvolutionFilter</function> returns the current 1D or 2D convolution filter kernel as an image.
 105             The one- or two-dimensional image is placed in <parameter>image</parameter> according to the
 106             specifications in <parameter>format</parameter> and <parameter>type</parameter>.
 107             No pixel transfer operations are performed on this image, but the relevant
 108             pixel storage modes are applied.
 109         </para>
 110         <para>
 111             If a non-zero named buffer object is bound to the <constant>GL_PIXEL_PACK_BUFFER</constant> target
 112             (see <citerefentry><refentrytitle>glBindBuffer</refentrytitle></citerefentry>) while a convolution filter is
 113             requested, <parameter>image</parameter> is treated as a byte offset into the buffer object's data store.
 114         </para>
 115         <para>
 116             Color components that are present in <parameter>format</parameter> but not included in the
 117             internal format of the filter are returned as zero.
 118             The assignments of internal color components to the components of <parameter>format</parameter>
 119             are as follows.
 120         </para>
 121         <informaltable frame="topbot">
 122             <tgroup cols="2" align="left">
 123                 <colspec/>
 124                 <colspec/>
 125                 <thead>
 126                     <row>
 127                         <entry rowsep="1" align="left"><emphasis role="bold">
 128                         Internal Component
 129                         </emphasis></entry>
 130                         <entry rowsep="1" align="left"><emphasis role="bold">
 131                         Resulting Component
 132                         </emphasis></entry>
 133                     </row>
 134                 </thead>
 135                 <tbody>
 136                     <row>
 137                         <entry align="left">
 138                         Red
 139                         </entry>
 140                         <entry align="left">
 141                         Red
 142                         </entry>
 143                     </row>
 144                     <row>
 145                         <entry align="left">
 146                         Green
 147                         </entry>
 148                         <entry align="left">
 149                         Green
 150                         </entry>
 151                     </row>
 152                     <row>
 153                         <entry align="left">
 154                         Blue
 155                         </entry>
 156                         <entry align="left">
 157                         Blue
 158                         </entry>
 159                     </row>
 160                     <row>
 161                         <entry align="left">
 162                         Alpha
 163                         </entry>
 164                         <entry align="left">
 165                         Alpha
 166                         </entry>
 167                     </row>
 168                     <row>
 169                         <entry align="left">
 170                         Luminance
 171                         </entry>
 172                         <entry align="left">
 173                         Red
 174                         </entry>
 175                     </row>
 176                     <row>
 177                         <entry align="left">
 178                         Intensity
 179                         </entry>
 180                         <entry align="left">
 181                         Red
 182                         </entry>
 183                     </row>
 184                 </tbody>
 185             </tgroup>
 186         </informaltable>
 187         <para>
 188         </para>
 189     </refsect1>
 190     <refsect1 id="notes"><title>Notes</title>
 191         <para>
 192             <function>glGetConvolutionFilter</function> is present only if <code>ARB_imaging</code> is returned when <citerefentry><refentrytitle>glGetString</refentrytitle></citerefentry>
 193             is called with an argument of <constant>GL_EXTENSIONS</constant>.
 194         </para>
 195         <para>
 196             The current separable 2D filter must be retrieved with
 197             <citerefentry><refentrytitle>glGetSeparableFilter</refentrytitle></citerefentry> rather than <function>glGetConvolutionFilter</function>.
 198         </para>
 199     </refsect1>
 200     <refsect1 id="errors"><title>Errors</title>
 201         <para>
 202             <constant>GL_INVALID_ENUM</constant> is generated if <parameter>target</parameter> is not one of the allowable
 203             values.
 204         </para>
 205         <para>
 206             <constant>GL_INVALID_ENUM</constant> is generated if <parameter>format</parameter> is not one of the allowable
 207             values.
 208         </para>
 209         <para>
 210             <constant>GL_INVALID_ENUM</constant> is generated if <parameter>type</parameter> is not one of the allowable
 211             values.
 212         </para>
 213         <para>
 214             <constant>GL_INVALID_OPERATION</constant> is generated if <parameter>type</parameter> is one of
 215             <constant>GL_UNSIGNED_BYTE_3_3_2</constant>,
 216             <constant>GL_UNSIGNED_BYTE_2_3_3_REV</constant>,
 217             <constant>GL_UNSIGNED_SHORT_5_6_5</constant>, or
 218             <constant>GL_UNSIGNED_SHORT_5_6_5_REV</constant>
 219             and <parameter>format</parameter> is not <constant>GL_RGB</constant>.
 220         </para>
 221         <para>
 222             <constant>GL_INVALID_OPERATION</constant> is generated if <parameter>type</parameter> is one of
 223             <constant>GL_UNSIGNED_SHORT_4_4_4_4</constant>,
 224             <constant>GL_UNSIGNED_SHORT_4_4_4_4_REV</constant>,
 225             <constant>GL_UNSIGNED_SHORT_5_5_5_1</constant>,
 226             <constant>GL_UNSIGNED_SHORT_1_5_5_5_REV</constant>,
 227             <constant>GL_UNSIGNED_INT_8_8_8_8</constant>,
 228             <constant>GL_UNSIGNED_INT_8_8_8_8_REV</constant>,
 229             <constant>GL_UNSIGNED_INT_10_10_10_2</constant>, or
 230             <constant>GL_UNSIGNED_INT_2_10_10_10_REV</constant>
 231             and <parameter>format</parameter> is neither <constant>GL_RGBA</constant> nor <constant>GL_BGRA</constant>.
 232         </para>
 233         <para>
 234             <constant>GL_INVALID_OPERATION</constant> is generated if a non-zero buffer object name is bound to the
 235             <constant>GL_PIXEL_PACK_BUFFER</constant> target and the buffer object's data store is currently mapped.
 236         </para>
 237         <para>
 238             <constant>GL_INVALID_OPERATION</constant> is generated if a non-zero buffer object name is bound to the
 239             <constant>GL_PIXEL_PACK_BUFFER</constant> target and the data would be packed to the buffer
 240             object such that the memory writes required would exceed the data store size.
 241         </para>
 242         <para>
 243             <constant>GL_INVALID_OPERATION</constant> is generated if a non-zero buffer object name is bound to the
 244             <constant>GL_PIXEL_PACK_BUFFER</constant> target and <parameter>image</parameter> is not evenly divisible
 245             into the number of bytes needed to store in memory a datum indicated by <parameter>type</parameter>.
 246         </para>
 247         <para>
 248             <constant>GL_INVALID_OPERATION</constant> is generated if <function>glGetConvolutionFilter</function> is executed
 249             between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry> and the corresponding
 250             execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
 251         </para>
 252     </refsect1>
 253     <refsect1 id="associatedgets"><title>Associated Gets</title>
 254         <para>
 255             <citerefentry><refentrytitle>glGetConvolutionParameter</refentrytitle></citerefentry>
 256         </para>
 257         <para>
 258             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_PIXEL_PACK_BUFFER_BINDING</constant>
 259         </para>
 260     </refsect1>
 261     <refsect1 id="seealso"><title>See Also</title>
 262         <para>
 263             <citerefentry><refentrytitle>glGetSeparableFilter</refentrytitle></citerefentry>,
 264             <citerefentry><refentrytitle>glConvolutionParameter</refentrytitle></citerefentry>,
 265             <citerefentry><refentrytitle>glConvolutionFilter1D</refentrytitle></citerefentry>,
 266             <citerefentry><refentrytitle>glConvolutionFilter2D</refentrytitle></citerefentry>
 267         </para>
 268     </refsect1>
 269     <refsect1 id="Copyright"><title>Copyright</title>
 270         <para>
 271             Copyright <trademark class="copyright"></trademark> 1991-2006
 272             Silicon Graphics, Inc. This document is licensed under the SGI
 273             Free Software B License. For details, see
 274             <ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
 275         </para>
 276     </refsect1>
 277 </refentry>