Return to glMaterial.xml CVS log

Up to [Development] / projects / ogl-sample / main / doc / gles / xml

OpenGL ES 1.0 and EGL 1.0 reference manual and man pages (written by
Claude Knaus, based on OpenGL SI man pages).

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.2//EN" "DTD/docbook/docbookx.dtd">

<!--
  License Applicability. Except to the extent portions of this file are
  made subject to an alternative license as permitted in the SGI Free
  Software License B, Version 1.1 (the "License"), the contents of this
  file are subject only to the provisions of the License. You may not use
  this file except in compliance with the License. You may obtain a copy
  of the License at Silicon Graphics, Inc., attn: Legal Services, 1600
  Amphitheatre Parkway, Mountain View, CA 94043-1351, or at:

  http://oss.sgi.com/projects/FreeB

  Note that, as provided in the License, the Software is distributed on an
  "AS IS" basis, with ALL EXPRESS AND IMPLIED WARRANTIES AND CONDITIONS
  DISCLAIMED, INCLUDING, WITHOUT LIMITATION, ANY IMPLIED WARRANTIES AND
  CONDITIONS OF MERCHANTABILITY, SATISFACTORY QUALITY, FITNESS FOR A
  PARTICULAR PURPOSE, AND NON-INFRINGEMENT.

  Original Code. The Original Code is: OpenGL ES Reference Manual,
  Version 1.0, released September 2003, developed by Silicon Graphics,
  Inc.  The Original Code is Copyright (c) 2003 Silicon Graphics, Inc.
  Copyright in any portions created by third parties is as indicated
  elsewhere herein.  All Rights Reserved.
-->

<refentry id="glMaterial">
  <refmeta>
    <refentrytitle>glMaterial</refentrytitle>
    <manvolnum>3G</manvolnum>
  </refmeta>

  <refnamediv>
    <refdescriptor>glMaterial</refdescriptor>
    <refname>glMaterialf</refname>
    <refname>glMaterialx</refname>
    <refname>glMaterialfv</refname>
    <refname>glMaterialxv</refname>
    <refpurpose>specify material parameters for the lighting model</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <title>C Specification</title>

    <funcsynopsis>
      <funcprototype>
        <funcdef>void <function>glMaterialf</function></funcdef>
        <paramdef>GLenum <parameter>face</parameter></paramdef>
        <paramdef>GLenum <parameter>pname</parameter></paramdef>
        <paramdef>GLfloat <parameter>param</parameter></paramdef>
      </funcprototype>
      <funcprototype>
        <funcdef>void <function>glMaterialx</function></funcdef>
        <paramdef>GLenum <parameter>face</parameter></paramdef>
        <paramdef>GLenum <parameter>pname</parameter></paramdef>
        <paramdef>GLfixed <parameter>param</parameter></paramdef>
      </funcprototype>
    </funcsynopsis>
  </refsynopsisdiv>

  <refsect1>
    <title>Parameters</title>

    <variablelist>
      <varlistentry>
        <term>
          <parameter>face</parameter>
        </term>

        <listitem>
          <para>Specifies which face or faces are being updated. Must be 
          <constant>GL_FRONT_AND_BACK</constant>.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <parameter>pname</parameter>
        </term>

        <listitem>
          <para>Specifies the single-valued material parameter of
          the face or faces that is being updated. Must be 
          <constant>GL_SHININESS</constant>.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <parameter>param</parameter>
        </term>

        <listitem>
          <para>Specifies the value that parameter 
          <constant>GL_SHININESS</constant> will be set to.</para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>

  <refsynopsisdiv>
    <title>C Specification</title>

    <funcsynopsis>
      <funcprototype>
        <funcdef>void <function>glMaterialfv</function></funcdef>
        <paramdef>GLenum <parameter>face</parameter></paramdef>
        <paramdef>GLenum <parameter>pname</parameter></paramdef>
        <paramdef>const GLfloat * <parameter>params</parameter></paramdef>
      </funcprototype>
      <funcprototype>
        <funcdef>void <function>glMaterialxv</function></funcdef>
        <paramdef>GLenum <parameter>face</parameter></paramdef>
        <paramdef>GLenum <parameter>pname</parameter></paramdef>
        <paramdef>const GLfixed * <parameter>params</parameter></paramdef>
      </funcprototype>
    </funcsynopsis>
  </refsynopsisdiv>

  <refsect1>
    <title>Parameters</title>

    <variablelist>
      <varlistentry>
        <term>
          <parameter>face</parameter>
        </term>

        <listitem>
          <para>Specifies which face or faces are being updated.
            Must be <constant>GL_FRONT_AND_BACK</constant>.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <parameter>pname</parameter>
        </term>

        <listitem>
          <para>Specifies the material parameter of the face or
          faces that is being updated. Must be one of 
          <constant>GL_AMBIENT</constant>, 
          <constant>GL_DIFFUSE</constant>, 
          <constant>GL_SPECULAR</constant>, 
          <constant>GL_EMISSION</constant>, 
          <constant>GL_SHININESS</constant>, or
          <constant>GL_AMBIENT_AND_DIFFUSE</constant>.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <parameter>params</parameter>
        </term>

        <listitem>
          <para>Specifies a pointer to the value or values that 
          <parameter>pname</parameter>

          will be set to.</para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>

  <refsect1>
    <title>Description</title>

    <para>
    <function>glMaterial</function>
    assigns values to material parameters.  There are two matched
    sets of material parameters. One, the <parameter>front-facing</parameter>
    set, is used to shade points, lines, and all polygons (when
    two-sided lighting is disabled), or just front-facing polygons
    (when two-sided lighting is enabled). The other set, 
    <parameter>back-facing</parameter>,
    is used to shade back-facing polygons only when two-sided
    lighting is enabled. Refer to the 
    <citerefentry><refentrytitle>glLightModel</refentrytitle></citerefentry>
    reference page for details concerning one- and two-sided
    lighting calculations.</para>

    <para>
    <function>glMaterial</function>
    takes three arguments. The first, <parameter>face</parameter>,
    must be <constant>GL_FRONT_AND_BACK</constant> and specifies that both
    front and back materials will be modified.
    The second, <parameter>pname</parameter>,
    specifies which of several parameters in one or both sets
    will be modified. The third, <parameter>params</parameter>,
    specifies what value or values will be assigned to the
    specified parameter.</para>

    <para>Material parameters are used in the lighting equation
    that is optionally applied to each vertex. The equation is
    discussed in the 
    <citerefentry><refentrytitle>glLightModel</refentrytitle></citerefentry>
    reference page. The parameters that can be specified using 
    <function>glMaterial</function>,
    and their interpretations by the lighting equation, are as follows:</para>

    <variablelist>
      <varlistentry>
        <term>
          <constant>GL_AMBIENT</constant>
        </term>

        <listitem>
          <para><parameter>params</parameter>
          contains four fixed-point or floating-point values that
          specify the ambient RGBA reflectance of the material.
          The values are not clamped. The initial ambient
          reflectance <!-- for both front- and back-facing materials--> is
          (0.2, 0.2, 0.2, 1.0).</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <constant>GL_DIFFUSE</constant>
        </term>

        <listitem>
          <para><parameter>params</parameter>
          contains four fixed-point or floating-point values that
          specify the diffuse RGBA reflectance of the material.
          The values are not clamped. The initial diffuse
          reflectance <!-- for both front- and back-facing materials--> is
          (0.8, 0.8, 0.8, 1.0).</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <constant>GL_SPECULAR</constant>
        </term>

        <listitem>
          <para><parameter>params</parameter>
          contains four fixed-point or floating-point values that
          specify the specular RGBA reflectance of the material.
          The values are not clamped. The initial specular
          reflectance <!-- for both front- and back-facing materials--> is
          (0, 0, 0, 1).</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <constant>GL_EMISSION</constant>
        </term>

        <listitem>
          <para><parameter>params</parameter>
          contains four fixed-point or floating-point values that
          specify the RGBA emitted light intensity of the material.
          The values are not clamped. The initial emission
          intensity <!-- for both front- and back-facing materials--> is
          (0, 0, 0, 1).</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <constant>GL_SHININESS</constant>
        </term>

        <listitem>
          <para><parameter>params</parameter>
          is a single fixed-point or floating-point value that
          specifies the RGBA specular exponent of the material.
          Only values in the range [0, 128] are accepted. The
          initial specular exponent <!-- for both front- and back-facing
          materials --> is 0.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <constant>GL_AMBIENT_AND_DIFFUSE</constant>
        </term>

        <listitem>
          <para>Equivalent to calling <function>glMaterial</function>
          twice with the same parameter values, once with 
          <constant>GL_AMBIENT</constant>
          and once with <constant>GL_DIFFUSE</constant>.</para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>

  <refsect1>
    <title>Notes</title>

    <para>To change the diffuse and ambient material per vertex, 
    color material can be used.
    To enable and disable
    <constant>GL_COLOR_MATERIAL</constant>, call
    <citerefentry><refentrytitle>glEnable</refentrytitle></citerefentry> and
    <citerefentry><refentrytitle>glDisable</refentrytitle></citerefentry> with
    argument <constant>GL_COLOR_MATERIAL</constant>.
    Color material is initially disabled.
    </para>

    <para>While the ambient, diffuse, specular and emission
    material parameters all have alpha components, only the diffuse
    alpha component is used in the lighting computation.</para>
  </refsect1>

  <refsect1>
    <title>Errors</title>

    <para>
      <constant>GL_INVALID_ENUM</constant> is generated if either 
      <parameter>face</parameter> or <parameter>pname</parameter> 
      is not an accepted value.
    </para>

    <para>
      <constant>GL_INVALID_VALUE</constant>
      is generated if a specular exponent outside the range [0, 128]
      is specified.
    </para>
  </refsect1>

  <refsect1>
    <title>See Also</title>

    <para>
      <citerefentry><refentrytitle>glEnable</refentrytitle></citerefentry>, 
      <citerefentry><refentrytitle>glLight</refentrytitle></citerefentry>, 
      <citerefentry><refentrytitle>glLightModel</refentrytitle></citerefentry>
    </para>
  </refsect1>
</refentry>