<?xml version="1.0" encoding="UTF-8"?>
<!--
 * Scilab ( https://www.scilab.org/ ) - This file is part of Scilab
 * Copyright (C) Pedro SOUZA
 *
 * Copyright (C) 2012 - 2016 - Scilab Enterprises
 *
 * This file is hereby licensed under the terms of the GNU GPL v2.0,
 * pursuant to article 5.3.4 of the CeCILL v.2.1.
 * This file was originally licensed under the terms of the CeCILL v2.1,
 * and continues to be available under such terms.
 * For more information, see the COPYING file which you should have received
 * along with this program.
 *
 -->
<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org"  xml:lang="en" scilab:needs-examples="no" xml:id="light_properties">
    <refnamediv>
        <refname>light properties</refname>
        <refpurpose>Light overview</refpurpose>
    </refnamediv>
    <refsection>
        <title>Description</title>
        <para>
            The light entity contains the properties to change lighting appearance.
            Lights aren't visible in the axes but they affect the surface appearance
            (see <link linkend="lighting">lighting</link> for a detailed explanation about
            lighting).
        </para>
        <para>
            Lights can be created using <link linkend="light">light</link> function,
            and deleted using <link linkend="delete">delete</link> function.
        </para>
        <scilab:image>
            plot3d();
            l = light();
            s = gce();
            s.diffuse_color = [0 0 0.8];
            s.ambient_color = [0 0 1];
            s.use_color_material = "off";
        </scilab:image>
    </refsection>
    <refsection>
        <title>Light properties list</title>
        <variablelist>
            <varlistentry>
                <term>visible: </term>
                <listitem>
                    <para>
                        This field defines if the light is enabled <literal>"on"</literal>
                        or disabled <literal>"off"</literal>.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>light_type: </term>
                <listitem>
                    <para>This field defines the type of light used. There are two
                        types available:<literal>"directional"</literal> and <literal>"point"</literal>.
                        Directional lights are positioned infinitely far from the surface
                        thus emitting parallel rays.
                    </para>
                    <para>
                        Point lights are defined as a point in space thus emitting rays in all
                        directions.
                        The default value is <literal>"point"</literal>.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>direction: </term>
                <listitem>
                    <para>This field defines the ray direction for directional light.
                        The direction can be changed using a 3 element vector <literal>"[x, y, z]"</literal>
                        representing a vector starting from the origin.
                    </para>
                    <para>
                        The default value is <literal>"[0 0 1]"</literal>.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>position: </term>
                <listitem>
                    <para>This field defines the light position for point light.
                        The position can be changed using a 3 element vector <literal>"[x, y, z]"</literal>.
                    </para>
                    <para>
                        The default value is <literal>"[0 0 1]"</literal>.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>ambient_color: </term>
                <listitem>
                    <para>This field defines the ambient color of the light.
                        The color is defined by a 3 element vector <literal>"[red, green, blue]"</literal>
                        with each element in the range [0, 1].
                    </para>
                    <para>
                        The default value is <literal>"[0.1 0.1 0.1]"</literal>.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>diffuse_color: </term>
                <listitem>
                    <para>This field defines the diffuse color of the light.
                        The color is defined by a 3 element vector <literal>"[red, green, blue]"</literal>
                        with each element in the range [0, 1].
                    </para>
                    <para>
                        The default value is <literal>"[1 1 1]"</literal>.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>specular_color: </term>
                <listitem>
                    <para>This field defines the specular color of the light.
                        The color is defined by a 3 element vector <literal>"[red, green, blue]"</literal>
                        with each element in the range [0, 1].
                    </para>
                    <para>
                        The default value is <literal>"[1 1 1]"</literal>.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>user_data: </term>
                <listitem>
                    <para>This field can be use to store any scilab variable and to retrieve it.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>tag: </term>
                <listitem>
                    <para>This field can be use to store a character string generally used to identify the light entity. It allows to give it a "name". Mainly used in conjunction with findobj() and get()/set() functions.</para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Examples</title>
        <programlisting role="example"><![CDATA[
        // point light
        plot3d;l=light();s=gce();
        for i=0:1000
            sleep(5);
            x = 2*cos(i*%pi/180);
            y = 2*sin(i*%pi/180);
            z = 2;
            l.position = [x y z];
        end

        // change light to directional mode
        l.light_type = "directional";
        l.direction = [1 0 1];
        l.ambient_color = [0.1 0.1 0.1];
        s.diffuse_color = [0.4 0.4 0.4];
        s.use_color_material = "off";
        s.color_flag = 0;
        s.thickness = 0;
        s.hiddencolor = -1;
        s.specular_color = [0.6 0.6 0.6];
        sleep(5000);

        l2 = light(ambient_color=[0 0 0], diffuse_color = [0.8 0.8 1], type="point", position=[0 3 4]);
        sleep(5000);
        delete(l);
        l2.specular_color = [1 0.6 0];
        ]]></programlisting>
    </refsection>
    <refsection role="see also">
        <title>See also</title>
        <simplelist type="inline">
            <member>
                <link linkend="lighting">lighting</link>
            </member>
            <member>
                <link linkend="light">light</link>
            </member>
            <member>
                <link linkend="delete">delete</link>
            </member>
        </simplelist>
    </refsection>
</refentry>
