<?xml version="1.0" encoding="UTF-8"?>
<!--
 * Scilab ( https://www.scilab.org/ ) - This file is part of Scilab
 * Copyright (C) ENPC - Jean-Philippe Chancelier
 * Copyright (C) - Scilab Enterprises - Clement David
 *
 * 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" xml:id="driver">
    <refnamediv>
        <refname>driver</refname>
        <refpurpose>select a graphics driver</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <synopsis>
            current_driver = driver()
            driver(driver_name)
            previous_driver = driver(driver_name)
        </synopsis>
    </refsynopsisdiv>
    <refsection>
        <title>Arguments</title>
        <variablelist>
            <varlistentry>
                <term>driver_name</term>
                <listitem>
                    <para>
                        a string, driver to be selected (case insensitive).
                    </para>
                </listitem>
                <term>current_driver</term>
                <listitem>
                    <para>a string, selected driver.</para>
                </listitem>
                <term>previous_driver</term>
                <listitem>
                    <para>a string, driver previously selected.</para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Description</title>
        <para>
            This function provides a switch between the different
            drivers for export or display.
        </para>
        <para>
            Direct rendering on the screen or off-screen export
            without any graphical user interface. This is available
            in the mode <literal>scilab-adv-cli</literal> (or also
            called <literal>-nw</literal>)
        </para>
        <para>
            Used without any input argument, the <function>driver</function>
            function returns the current graphics driver name.
        </para>
    </refsection>
    <refsection>
        <title>Screen output</title>
        <para>
            To display graphic into a new window instead of off-screen format. This is the default behavior of Scilab.
        </para>
        <para>
            It is possible to use the "null" format to direct graphics to nothing.
        </para>
        <variablelist>
            <varlistentry>
                <term>X11 or Rec</term>
                <listitem>
                    <para>output to the screen of the computer.</para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Supported vectorial formats</title>
        <para>
            The selected driver can be one of the following vectorial format:
        </para>
        <variablelist>
            <varlistentry>
                <term>Pos or ps</term>
                <listitem>
                    <para>output into Postscript format.</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>PDF</term>
                <listitem>
                    <para>output into PDF format.</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>SVG</term>
                <listitem>
                    <para>output into SVG format.</para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Supported bitmap formats</title>
        <para>
            The selected driver can be one of the following bitmap
            format:
        </para>
        <variablelist>
            <varlistentry>
                <term>GIF</term>
                <listitem>
                    <para>output into GIF format.</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>PNG</term>
                <listitem>
                    <para>output into PNG format.</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>JPEG or JPG</term>
                <listitem>
                    <para>output into JPEG format.</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>BMP</term>
                <listitem>
                    <para>output into BMP format.</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>PPM</term>
                <listitem>
                    <para>output into portable pixmap (PPM) format.</para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Remark</title>
        <para>
            To redirect the graphic output to a GIF file (which will be
            written in the temporary directory), you can use the
            following example:
        </para>
        <programlisting role="example"><![CDATA[
previous_driver = driver('GIF');
xinit(TMPDIR+'/mygiffile.gif');
plot3d();
xend();
driver(previous_driver); // Bring back the previous behavior of Scilab
 ]]></programlisting>
        <para>
            For example if one has generated a sequence of GIF files
            named <literal>img*.gif</literal> it is possible to build
            an animated GIF file (named <literal>anim.gif</literal>) by
        </para>
        <synopsis>
            convert -delay 10  img*.gif anim.gif
        </synopsis>
    </refsection>
    <refsection role="see also">
        <title>See also</title>
        <simplelist type="inline">
            <member>
                <link linkend="xinit">xinit</link>
            </member>
            <member>
                <link linkend="xend">xend</link>
            </member>
        </simplelist>
    </refsection>
    <refsection>
        <title>History</title>
        <revhistory>
            <revision>
                <revnumber>5.4.0</revnumber>
                <revremark>
                    <itemizedlist>
                        <listitem>
                            Return the previous driver value.
                        </listitem>
                        <listitem>
                            Enable off-screen export. Scilab exports graphics without opening a new window.
                        </listitem>
                        <listitem>
                            Support of new bitmap formats: PNG, JPEG and BMP.
                        </listitem>
                        <listitem>
                            Support of new vectorial formats: PDF and SVG.
                        </listitem>
                        <listitem>
                            The function accepts lower and upper case argument.
                        </listitem>
                        <listitem>
                            Fig driver is no longer supported.
                        </listitem>
                    </itemizedlist>
                </revremark>
            </revision>
        </revhistory>
    </refsection>
</refentry>
