upstream-man-pages/man2/xhtml/glMaterial.xml

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "xhtml1-transitional.dtd">
   2 <!-- saved from url=(0013)about:internet -->
   3 <?xml-stylesheet type="text/xsl" href="mathml.xsl"?><html xmlns="http://www.w3.org/1999/xhtml" xmlns:pref="http://www.w3.org/2002/Math/preference" pref:renderer="mathplayer-dl"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>glMaterial</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /></head><body><div class="refentry" lang="en" xml:lang="en"><a id="glMaterial"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>glMaterial — specify material parameters for the lighting model</p></div><div class="refsynopsisdiv"><h2>C Specification</h2><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0"><tr><td><code class="funcdef">void <b class="fsfunc">glMaterialf</b>(</code></td><td>GLenum  </td><td><var class="pdparam">face</var>, </td></tr><tr><td> </td><td>GLenum  </td><td><var class="pdparam">pname</var>, </td></tr><tr><td> </td><td>GLfloat  </td><td><var class="pdparam">param</var><code>)</code>;</td></tr></table></div><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0"><tr><td><code class="funcdef">void <b class="fsfunc">glMateriali</b>(</code></td><td>GLenum  </td><td><var class="pdparam">face</var>, </td></tr><tr><td> </td><td>GLenum  </td><td><var class="pdparam">pname</var>, </td></tr><tr><td> </td><td>GLint  </td><td><var class="pdparam">param</var><code>)</code>;</td></tr></table></div></div><div class="refsect1" lang="en" xml:lang="en"><a id="parameters"></a><h2>Parameters</h2><div class="variablelist"><dl><dt><span class="term"><em class="parameter"><code>face</code></em></span></dt><dd><p>
   4                     Specifies which face or faces are being updated.
   5                     Must be one of
   6                     <code class="constant">GL_FRONT</code>,
   7                     <code class="constant">GL_BACK</code>, or
   8                     <code class="constant">GL_FRONT_AND_BACK</code>.
   9                 </p></dd><dt><span class="term"><em class="parameter"><code>pname</code></em></span></dt><dd><p>
  10                     Specifies the single-valued material parameter of the face or faces
  11                     that is being updated.
  12                     Must be <code class="constant">GL_SHININESS</code>.
  13                 </p></dd><dt><span class="term"><em class="parameter"><code>param</code></em></span></dt><dd><p>
  14                     Specifies the value that parameter <code class="constant">GL_SHININESS</code> will be set to.
  15                 </p></dd></dl></div></div><div class="refsynopsisdiv"><h2>C Specification</h2><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0"><tr><td><code class="funcdef">void <b class="fsfunc">glMaterialfv</b>(</code></td><td>GLenum  </td><td><var class="pdparam">face</var>, </td></tr><tr><td> </td><td>GLenum  </td><td><var class="pdparam">pname</var>, </td></tr><tr><td> </td><td>const GLfloat *  </td><td><var class="pdparam">params</var><code>)</code>;</td></tr></table></div><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0"><tr><td><code class="funcdef">void <b class="fsfunc">glMaterialiv</b>(</code></td><td>GLenum  </td><td><var class="pdparam">face</var>, </td></tr><tr><td> </td><td>GLenum  </td><td><var class="pdparam">pname</var>, </td></tr><tr><td> </td><td>const GLint *  </td><td><var class="pdparam">params</var><code>)</code>;</td></tr></table></div></div><div class="refsect1" lang="en" xml:lang="en"><a id="parameters2"></a><h2>Parameters</h2><div class="variablelist"><dl><dt><span class="term"><em class="parameter"><code>face</code></em></span></dt><dd><p>
  16                     Specifies which face or faces are being updated.
  17                     Must be one of
  18                     <code class="constant">GL_FRONT</code>,
  19                     <code class="constant">GL_BACK</code>, or
  20                     <code class="constant">GL_FRONT_AND_BACK</code>.
  21                 </p></dd><dt><span class="term"><em class="parameter"><code>pname</code></em></span></dt><dd><p>
  22                     Specifies the material parameter of the face or faces that is being updated.
  23                     Must be one of
  24                     <code class="constant">GL_AMBIENT</code>,
  25                     <code class="constant">GL_DIFFUSE</code>,
  26                     <code class="constant">GL_SPECULAR</code>,
  27                     <code class="constant">GL_EMISSION</code>,
  28                     <code class="constant">GL_SHININESS</code>,
  29                     <code class="constant">GL_AMBIENT_AND_DIFFUSE</code>, or
  30                     <code class="constant">GL_COLOR_INDEXES</code>.
  31                 </p></dd><dt><span class="term"><em class="parameter"><code>params</code></em></span></dt><dd><p>
  32                     Specifies a pointer to the value or values that <em class="parameter"><code>pname</code></em> will be set to.
  33                 </p></dd></dl></div></div><div class="refsect1" lang="en" xml:lang="en"><a id="description"></a><h2>Description</h2><p>
  34             <code class="function">glMaterial</code> assigns values to material parameters.
  35             There are two matched sets of material parameters.
  36             One,
  37             the <span class="emphasis"><em>front-facing</em></span> set,
  38             is used to shade points,
  39             lines,
  40             bitmaps,
  41             and all polygons
  42             (when two-sided lighting is disabled),
  43             or just front-facing polygons
  44             (when two-sided lighting is enabled).
  45             The other set,
  46             <span class="emphasis"><em>back-facing</em></span>,
  47             is used to shade back-facing polygons only when two-sided lighting is enabled.
  48             Refer to the <a class="citerefentry" href="glLightModel.xml"><span class="citerefentry"><span class="refentrytitle">glLightModel</span></span></a> reference page for details concerning one- and
  49             two-sided lighting calculations.
  50         </p><p>
  51             <code class="function">glMaterial</code> takes three arguments.
  52             The first,
  53             <em class="parameter"><code>face</code></em>,
  54             specifies whether the
  55             <code class="constant">GL_FRONT</code> materials, the
  56             <code class="constant">GL_BACK</code> materials, or both
  57             <code class="constant">GL_FRONT_AND_BACK</code> materials will be modified.
  58             The second,
  59             <em class="parameter"><code>pname</code></em>,
  60             specifies which of several parameters in one or both sets will be modified.
  61             The third,
  62             <em class="parameter"><code>params</code></em>,
  63             specifies what value or values will be assigned to the specified parameter.
  64         </p><p>
  65             Material parameters are used in the lighting equation that is optionally
  66             applied to each vertex.
  67             The equation is discussed in the <a class="citerefentry" href="glLightModel.xml"><span class="citerefentry"><span class="refentrytitle">glLightModel</span></span></a> reference page.
  68             The parameters that can be specified using <code class="function">glMaterial</code>,
  69             and their interpretations by the lighting equation, are as follows:
  70         </p><div class="variablelist"><dl><dt><span class="term"><code class="constant">GL_AMBIENT</code></span></dt><dd><p>
  71                         <em class="parameter"><code>params</code></em> contains four integer or floating-point values that specify
  72                         the ambient RGBA reflectance of the material.
  73                         Integer values are mapped linearly such that the most positive representable
  74                         value maps to 1.0,
  75                         and the most negative representable value maps to
  76                         <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
  77
  78                             <mml:mn>-1.0</mml:mn>
  79                         </mml:math>.
  80                         Floating-point values are mapped directly.
  81                         Neither integer nor floating-point values are clamped.
  82                         The initial ambient reflectance for both front- and back-facing materials
  83                         is (0.2, 0.2, 0.2, 1.0).
  84                     </p></dd><dt><span class="term"><code class="constant">GL_DIFFUSE</code></span></dt><dd><p>
  85                         <em class="parameter"><code>params</code></em> contains four integer or floating-point values that specify
  86                         the diffuse RGBA reflectance of the material.
  87                         Integer values are mapped linearly such that the most positive representable
  88                         value maps to 1.0,
  89                         and the most negative representable value maps to
  90                         <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
  91
  92                             <mml:mn>-1.0</mml:mn>
  93                         </mml:math>.
  94                         Floating-point values are mapped directly.
  95                         Neither integer nor floating-point values are clamped.
  96                         The initial diffuse reflectance for both front- and back-facing materials
  97                         is (0.8, 0.8, 0.8, 1.0).
  98                     </p></dd><dt><span class="term"><code class="constant">GL_SPECULAR</code></span></dt><dd><p>
  99                         <em class="parameter"><code>params</code></em> contains four integer or floating-point values that specify
 100                         the specular RGBA reflectance of the material.
 101                         Integer values are mapped linearly such that the most positive representable
 102                         value maps to 1.0,
 103                         and the most negative representable value maps to
 104                         <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
 105
 106                             <mml:mn>-1.0</mml:mn>
 107                         </mml:math>.
 108                         Floating-point values are mapped directly.
 109                         Neither integer nor floating-point values are clamped.
 110                         The initial specular reflectance for both front- and back-facing materials
 111                         is (0, 0, 0, 1).
 112                     </p></dd><dt><span class="term"><code class="constant">GL_EMISSION</code></span></dt><dd><p>
 113                         <em class="parameter"><code>params</code></em> contains four integer or floating-point values that specify
 114                         the RGBA emitted light intensity of the material.
 115                         Integer values are mapped linearly such that the most positive representable
 116                         value maps to 1.0,
 117                         and the most negative representable value maps to
 118                         <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
 119
 120                             <mml:mn>-1.0</mml:mn>
 121                         </mml:math>.
 122                         Floating-point values are mapped directly.
 123                         Neither integer nor floating-point values are clamped.
 124                         The initial emission intensity for both front- and back-facing materials
 125                         is (0, 0, 0, 1).
 126                     </p></dd><dt><span class="term"><code class="constant">GL_SHININESS</code></span></dt><dd><p>
 127                         <em class="parameter"><code>params</code></em> is a single integer or floating-point value that specifies
 128                         the RGBA specular exponent of the material.
 129                         Integer and floating-point values are mapped directly.
 130                         Only values in the range
 131                         <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
 132
 133                             <mml:mfenced open="[" close="]">
 134                                 <mml:mn>0</mml:mn>
 135                                 <mml:mn>128</mml:mn>
 136                             </mml:mfenced>
 137                         </mml:math>
 138                         are accepted.
 139                         The initial specular exponent for both front- and back-facing materials
 140                         is 0.
 141                     </p></dd><dt><span class="term"><code class="constant">GL_AMBIENT_AND_DIFFUSE</code></span></dt><dd><p>
 142                         Equivalent to calling <code class="function">glMaterial</code> twice with the same parameter values,
 143                         once with <code class="constant">GL_AMBIENT</code> and once with <code class="constant">GL_DIFFUSE</code>.
 144                     </p></dd><dt><span class="term"><code class="constant">GL_COLOR_INDEXES</code></span></dt><dd><p>
 145                         <em class="parameter"><code>params</code></em> contains three integer or floating-point values specifying
 146                         the color indices for ambient,
 147                         diffuse,
 148                         and specular lighting.
 149                         These three values,
 150                         and <code class="constant">GL_SHININESS</code>,
 151                         are the only material values used by the color index mode lighting equation.
 152                         Refer to the <a class="citerefentry" href="glLightModel.xml"><span class="citerefentry"><span class="refentrytitle">glLightModel</span></span></a> reference page for a discussion
 153                         of color index lighting.
 154                     </p></dd></dl></div></div><div class="refsect1" lang="en" xml:lang="en"><a id="notes"></a><h2>Notes</h2><p>
 155             The material parameters can be updated at any time.
 156             In particular,
 157             <code class="function">glMaterial</code> can be called between a call to <a class="citerefentry" href="glBegin.xml"><span class="citerefentry"><span class="refentrytitle">glBegin</span></span></a> and the corresponding
 158             call to <a class="citerefentry" href="glEnd.xml"><span class="citerefentry"><span class="refentrytitle">glEnd</span></span></a>.
 159             If only a single material parameter is to be changed per vertex,
 160             however,
 161             <a class="citerefentry" href="glColorMaterial.xml"><span class="citerefentry"><span class="refentrytitle">glColorMaterial</span></span></a> is preferred over <code class="function">glMaterial</code>
 162             (see <a class="citerefentry" href="glColorMaterial.xml"><span class="citerefentry"><span class="refentrytitle">glColorMaterial</span></span></a>).
 163         </p><p>
 164             While the ambient, diffuse, specular and emission material parameters
 165             all have alpha components, only the diffuse alpha component is used in
 166             the lighting computation.
 167         </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="errors"></a><h2>Errors</h2><p>
 168             <code class="constant">GL_INVALID_ENUM</code> is generated if either <em class="parameter"><code>face</code></em> or <em class="parameter"><code>pname</code></em> is not
 169             an accepted value.
 170         </p><p>
 171             <code class="constant">GL_INVALID_VALUE</code> is generated if a specular exponent outside the range
 172             <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
 173
 174                 <mml:mfenced open="[" close="]">
 175                     <mml:mn>0</mml:mn>
 176                     <mml:mn>128</mml:mn>
 177                 </mml:mfenced>
 178             </mml:math>
 179             is specified.
 180         </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="associatedgets"></a><h2>Associated Gets</h2><p>
 181             <a class="citerefentry" href="glGetMaterial.xml"><span class="citerefentry"><span class="refentrytitle">glGetMaterial</span></span></a>
 182         </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="seealso"></a><h2>See Also</h2><p>
 183             <a class="citerefentry" href="glColorMaterial.xml"><span class="citerefentry"><span class="refentrytitle">glColorMaterial</span></span></a>,
 184             <a class="citerefentry" href="glLight.xml"><span class="citerefentry"><span class="refentrytitle">glLight</span></span></a>,
 185             <a class="citerefentry" href="glLightModel.xml"><span class="citerefentry"><span class="refentrytitle">glLightModel</span></span></a>
 186         </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="Copyright"></a><h2>Copyright</h2><p>
 187             Copyright <span class="trademark"></span>© 1991-2006
 188             Silicon Graphics, Inc. This document is licensed under the SGI
 189             Free Software B License. For details, see
 190             <a class="ulink" href="http://oss.sgi.com/projects/FreeB/" target="_top">http://oss.sgi.com/projects/FreeB/</a>.
 191         </p></div></div></body></html>