Return to glLightModel.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="glLightModel">
  <refmeta>
    <refentrytitle>glLightModel</refentrytitle>
    <manvolnum>3G</manvolnum>
  </refmeta>

  <refnamediv>
    <refdescriptor>glLightModel</refdescriptor>
    <refname>glLightModelf</refname>
    <refname>glLightModelx</refname>
    <refname>glLightModelfv</refname>
    <refname>glLightModelxv</refname>
    <refpurpose>set the lighting model parameters</refpurpose>
  </refnamediv>

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

    <funcsynopsis>
      <funcprototype>
        <funcdef>void <function>glLightModelf</function></funcdef>
        <paramdef>GLenum <parameter>pname</parameter></paramdef>
        <paramdef>GLfloat <parameter>param</parameter></paramdef>
      </funcprototype>
      <funcprototype>
        <funcdef>void <function>glLightModelx</function></funcdef>
        <paramdef>GLenum <parameter>pname</parameter></paramdef>
        <paramdef>GLfixed <parameter>param</parameter></paramdef>
      </funcprototype>
    </funcsynopsis>
  </refsynopsisdiv>

  <refsect1>
    <title>Parameters</title>

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

        <listitem>
          <para>Specifies a single-valued lighting model parameter.  Must be 
          <constant>GL_LIGHT_MODEL_TWO_SIDE</constant>.</para>
        </listitem>
      </varlistentry>

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

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

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

    <funcsynopsis>
      <funcprototype>
        <funcdef>void <function>glLightModelfv</function></funcdef>
        <paramdef>GLenum <parameter>pname</parameter></paramdef>
        <paramdef>const GLfloat * <parameter>params</parameter></paramdef>
      </funcprototype>
      <funcprototype>
        <funcdef>void <function>glLightModelxv</function></funcdef>
        <paramdef>GLenum <parameter>pname</parameter></paramdef>
        <paramdef>const GLfixed * <parameter>params</parameter></paramdef>
      </funcprototype>
    </funcsynopsis>
  </refsynopsisdiv>

  <refsect1>
    <title>Parameters</title>

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

        <listitem>
          <para>Specifies a lighting model parameter. 
          <constant>GL_LIGHT_MODEL_AMBIENT</constant> and 
          <constant>GL_LIGHT_MODEL_TWO_SIDE</constant> are accepted.</para>
        </listitem>
      </varlistentry>

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

        <listitem>
          <para>Specifies a pointer to the value or values that 
          <parameter>params</parameter> will be set to.</para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>

  <refsect1>
    <title>Description</title>

    <para><function>glLightModel</function> sets the lighting model parameter.
    <parameter>pname</parameter> names a parameter and
    <parameter>params</parameter>
    gives the new value. There are two lighting model parameters:</para>

    <variablelist>
      <varlistentry>
        <term>
          <constant>GL_LIGHT_MODEL_AMBIENT</constant>
        </term>

        <listitem>
          <para><parameter>params</parameter> 
          contains four fixed-point or floating-point values that
          specify the ambient intensity of the entire scene.
          The values are not clamped. The initial value is
          (0.2, 0.2, 0.2, 1.0).</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <constant>GL_LIGHT_MODEL_TWO_SIDE</constant>
        </term>

        <listitem>
          <para><parameter>params</parameter> 
          is a single fixed-point or floating-point value that
          specifies whether one- or two-sided lighting calculations
          are done for polygons. It has no effect on the lighting
          calculations for points, lines, or bitmaps. If 
          <parameter>params</parameter>
          is 0, one-sided lighting is specified, and only
          the <parameter>front</parameter>
          material parameters are used in the lighting equation.
          Otherwise, two-sided lighting is specified. In this case,
          vertices of back-facing polygons are lighted using the 
          <parameter>back</parameter>
          material parameters, and have their normals reversed
          before the lighting equation is evaluated. Vertices of
          front-facing polygons are always lighted using the 
          <parameter>front</parameter>
          material parameters, with no change to their normals. The
          initial value is 0.</para>
        </listitem>
      </varlistentry>
    </variablelist>

    <para>The lighted color of a vertex is the sum of the material
    emission intensity, the product of the material ambient
    reflectance and the lighting model full-scene ambient
    intensity, and the contribution of each enabled light source.
    Each light source contributes the sum of three terms: ambient,
    diffuse, and specular. The ambient light source contribution is
    the product of the material ambient reflectance and the light's
    ambient intensity. The diffuse light source contribution is the
    product of the material diffuse reflectance, the light's
    diffuse intensity, and the dot product of the vertex's normal
    with the normalized vector from the vertex to the light source.
    The specular light source contribution is the product of the
    material specular reflectance, the light's specular intensity,
    and the dot product of the normalized vertex-to-eye and
    vertex-to-light vectors, raised to the power of the shininess
    of the material. All three light source contributions are
    attenuated equally based on the distance from the vertex to the
    light source and on light source direction, spread exponent,
    and spread cutoff angle. All dot products are replaced with 0
    if they evaluate to a negative value.</para>

    <para>The alpha component of the resulting lighted color is set
    to the alpha value of the material diffuse reflectance.</para>
  </refsect1>

  <refsect1>
    <title>Errors</title>

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

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

    <para>
    <citerefentry><refentrytitle>glLight</refentrytitle></citerefentry>, 
    <citerefentry><refentrytitle>glMaterial</refentrytitle></citerefentry>
    </para>
  </refsect1>
</refentry>