<?xml version="1.0"?>

<book version="5.0" xml:lang="en" xmlns="http://docbook.org/ns/docbook">
  <title>WM3D XML Document</title>
  <titleabbrev>WM3D XML</titleabbrev>
  <bookinfo>
    <copyright>
      <year>2012</year>
      <holder>Copyright (C) tamanegi</holder>
    </copyright>
    <author>
      <affiliation>
        <address><email>tamanegi@users.sourceforge.jp</email></address>
      </affiliation>
    </author>
  </bookinfo>
  <preface>
    <title>Introduction</title>
    <para>
      <ulink url="http://sourceforge.jp/projects/watermelon">Wm3d/Watermelon</ulink>
      are flash molecular viewers written with
      <ulink url="http://www.haxe.org">haXe</ulink> for flash11/flash10.
      Watermelon is a predecessor of wm3d and is obsolete now.
      This document describes the XML elements and their attributes available in wm3d.
    </para>
    <para>
      This document does not contain general usages of the wm3d. They will be
      available at
      <ulink url="http://sourceforge.jp/projects/watermelon/wiki">Project Wiki</ulink>.
    </para>
  </preface>
  <chapter id="c_datatypes">
    <title>Data Types and Coordinate System</title>
    <para>
      WM3D uses several types of values (ex. Integer, Float, String).
      Values must be quoted regardless of value types.
    </para>
    <para>
      Examples:
      <simplelist>
        <member><emphasis>&lt;ATOM radius="2.0" quality="3" pos="0 0 0" \&gt;</emphasis></member>
        <member><emphasis>&lt;LABEL text="N-terminus" pos="0 0 0" \&gt;</emphasis></member>
      </simplelist>
    </para>
    <section id="s_datatype">
      <title>Data Types</title>
      <important id="ss_basic">
        <title>Basic Types (Int, Float, String)</title>
        <para>
          Standard types. Integer, Float, and String values.
          Integer values are also valid for float values, see following samples.
          String accepts all most all kinds of quoted values.
          <simplelist>
            <member>Integer(Int): "1", "0", "-3"</member>
            <member>Float: "1.1", "1.0", "1"</member>
            <member>String: "3", "1.1", "text", "foobar"</member>
          </simplelist>
        </para>
      </important>
      <important id="ss_point3d">
        <title>Point3D</title>
        <para>
          Point3D is a three-dimension position/vector.
          This must have space-separated three float values.
          Leading, trailing, and any consecutive spaces are ignored in
          versions 0.22 or later.
          Do not add such spaces in versions older than 0.22.
        </para>
        <para>
          Examples:
          <simplelist>
            <member>"4 5 6"</member>
            <member>"   2.0 1.0 3.0 "</member>
            <member>"-2.0  1.0   3.0   "</member>
            <member>" -2.0 1.0 3"</member>
          </simplelist>
          Note: for versions before 0.22, only the first one is valid.
        </para>
      </important>
      <important id="ss_color">
        <title>Color</title>
        <para>
          Colors can be specified either in a string such as "red" or
          a triplet of hexadecimal values (red, green, and blue).
        </para>
        <para>
          Examples:
          <simplelist>
            <member>"red"</member>
            <member>"0xFF0000" (same as "red")</member>
            <member>"0x0000FF" (same as "blue")</member>
            <member>"cyan"</member>
          </simplelist>
          All the predefined values are in the following.
        </para>
        <simplelist>
          <member><emphasis>COLORNAME : RGB VALUE</emphasis></member>
          <member>white : 0xFFFFFF</member>
          <member>silver : 0xC0C0C0</member>
          <member>gray : 0x808080</member>
          <member>black : 0x000000</member>
          <member>cyan : 0x00FFFF</member>
          <member>navy : 0x000080</member>
          <member>blue : 0x0000FF</member>
          <member>lime : 0x00FF00</member>
          <member>green : 0x008000</member>
          <member>springgreen : 0x00FF7F</member>
          <member>limegreen : 0x32CD32</member>
          <member>darkgreen : 0x006400</member>
          <member>khaki : 0xF0E68C</member>
          <member>orange : 0xFFA500</member>
          <member>yellow : 0xFFFF00</member>
          <member>brown : 0xA52A2A</member>
          <member>chocolate : 0xD2691E</member>
          <member>gold : 0xFFD700</member>
          <member>violet : 0xEE82EE</member>
          <member>salmon : 0xFA8072</member>
          <member>purple : 0x800080</member>
          <member>red : 0xFF0000</member>
          <member>magenta : 0xFF00FF</member>
          <member>pink : 0xFFC0CB</member>
        </simplelist>
      </important>
    </section>
    <section id="s_coordinatesystem">
      <title>Coordinate System</title>
      <para>
        Coordinate system of wm3d is right-handed.
        <simplelist>
          <member>X-axis: towards right</member>
          <member>Y-axis: towards down</member>
          <member>Z-axis: towards display</member>
        </simplelist>
        The geometric center is placed on the origin(0,0,0), unless the
        origin is specified by the user.
        Camera locates on the Z-axis and can move along the Z-axis
        (its z-position should be negative).
        Camera is always looking towards positive-z direction.
      </para>
    </section>
  </chapter>
  <chapter id="c_element_list">
    <title>XML elements and attributes</title>
    <section id="e_wmxml">
      <title>WMXML</title>
      <important>
        <title>Description</title>
        <para><emphasis>Level: </emphasis>top</para>
        <para>
          Top level element of this XML.
        </para>
      </important>
      <important>
        <title>Parent Elements</title>
        <para>nothing</para>
      </important>
      <important>
        <title>Child Elements</title>
        <para>
          <link linkend="e_global">GLOBAL</link>,
          <link linkend="e_scene">SCENE</link>
        </para>
      </important>
      <important>
        <title>Attributes</title>
        <para>nothing</para>
      </important>
    </section>
    <section id="e_global">
      <title>GLOBAL</title>
      <important>
        <title>Description</title>
        <para><emphasis>Level: </emphasis>2nd</para>
        <para>
          Global setting of the movie such as light, mouse, and view. Some
          parameters of this element are inherited to the
          <link linkend="e_local">scene local setting</link>.
        </para>
      </important>
      <important>
        <title>Parent Elements</title>
        <para><link linkend="e_wmxml">WMXML</link></para>
      </important>
      <important>
        <title>Child Elements</title>
        <para>
          <link linkend="e_atom">ATOM</link>,
          <link linkend="e_bond">BOND</link>,
          <link linkend="e_ribbon">RIBBON</link>,
          <link linkend="e_coil">COIL</link>,
          <link linkend="e_shape">SHAPE</link>,
          <link linkend="e_obj3d">OBJ3D</link>,
          <link linkend="e_label">LABEL</link>,
          <link linkend="e_camera">CAMERA</link>,
          <link linkend="e_protect">PROTECT</link>,
          <link linkend="e_wheel">WHEEL</link>,
          <link linkend="e_matrix">MATRIX</link>,
          <link linkend="e_radius">RADIUS</link>,
          <link linkend="e_autoscale">AUTOSCALE</link>
        </para>
        <para>
          ATOM, BOND, RIBBON, COIL, SHAPE, OBJ3D, LABEL elements are the default
          setting of these primitives. The settings such as color, radius here
          define the global default. Setting here is used as the default in
          all the SCENEs.
        </para>
      </important>
      <important>
        <title>Attributes</title>
        <variablelist>
          <varlistentry>
            <term><emphasis>light</emphasis> (type:<link linkend="ss_point3d">Point3D</link>) = "-1 1 -1"</term>
            <listitem>
              <para>
                Direction of light. Only one directional light is available in
                wm3d.  The inputted direction will be automatically normalized.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term><emphasis>arrate</emphasis> (type:Float) = "1.5"</term>
            <listitem>
              <para>
                The rate of automatic rotation in degree/frame.
                Set to 0 if you want to prevent automatic rotation.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term><emphasis>framerate</emphasis> (type:Int) = ?</term>
            <listitem>
              <para>
                The framerate of the flash movie. Default value is
                determined at the compilation.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term><emphasis>play</emphasis> (type:Int) = 0</term>
            <listitem>
              <para>
                After loading scene, scenes are played forward or backward for
                positive or negative value, respectively. If there is only one
                scene, this attribute does not make sense.
              </para>
              <para>
                You can start playing by typing "p"(forward) or "P"(backward)
                without setting this option.
              </para>
              <para>
                Even when this value is 0, the scenes are automatically played
                once while loading scenes. To prevent this playing while loading
                function, set <emphasis>readbackground</emphasis> attribute below.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term><emphasis>playrate</emphasis> (type:Float) = 3.0</term>
            <listitem>
              <para>
                The framerate of play. The value means number of the frames
                (at most) played in a second.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term><emphasis>readbackground (abbr.:bgread,readbg)</emphasis> (type:Void)</term>
            <listitem>
              <para>
                If this parameter is set to any value, wm3d does not play
                scenes during loading them.  Parameter to this attribute is
                simply ignored, though you must give dummy parameter.
                If there is only one scene, this attribute does nothing.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </important>
    </section>
    <section id="e_camera">
      <title>CAMERA</title>
      <important>
        <title>Description</title>
        <para><emphasis>Level: </emphasis>3rd</para>
        <para>
          Position of camera. Only z-position can be modified now.
        </para>
      </important>
      <important>
        <title>Parent Elements</title>
        <para>
          <link linkend="e_global">GLOBAL</link>
        </para>
      </important>
      <important>
        <title>Child Elements</title>
        <para>nothing</para>
      </important>
      <important>
        <title>Attributes</title>
        <variablelist>
          <varlistentry>
            <term><emphasis>z</emphasis> (type:Float) = -max(stageWidth,stageHeight)*2</term>
            <listitem>
              <para>
                The z-position of the camera.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </important>
    </section>
    <section id="e_protect">
      <title>PROTECT</title>
      <important>
        <title>Description</title>
        <para><emphasis>Level: </emphasis>3rd</para>
        <para>
          A flag to hide data from users.
          If this element is added, users cannot edit or save XML data.
          This protection is far from the perfect.
          Use at your own risk.
        </para>
      </important>
      <important>
        <title>Parent Elements</title>
        <para>
          <link linkend="e_global">GLOBAL</link>
        </para>
      </important>
      <important>
        <title>Child Elements</title>
        <para>nothing</para>
      </important>
      <important>
        <title>Attributes</title>
        <para>nothing</para>
      </important>
    </section>
    <section id="e_matrix">
      <title>MATRIX</title>
      <important>
        <title>Description</title>
        <para><emphasis>Level: </emphasis>3rd</para>
        <para>
          4x4 matrix, Affine transformation matrix, for
          rotation/translation/scaling.
          This element is used to restore the view.
          This data is not intended to write manually.
          Please use save function (type "S") to obtain the view.
        </para>
      </important>
      <important>
        <title>Parent Elements</title>
        <para>
          <link linkend="e_global">GLOBAL</link>
        </para>
      </important>
      <important>
        <title>Child Elements</title>
        <para>nothing</para>
      </important>
      <important>
        <title>Attributes</title>
        <variablelist>
          <varlistentry>
            <term><emphasis>data</emphasis> (type:Float*16) = null</term>
            <listitem>
              <para>
                Components of the 4x4 transformation matrix.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </important>
    </section>
    <section id="e_wheel">
      <title>WHEEL</title>
      <important>
        <title>Description</title>
        <para><emphasis>Level: </emphasis>3rd</para>
        <para>
          Scaling factors for mouse wheel operations.
          The modification of those values are available only through this
          setting.
        </para>
      </important>
      <important>
        <title>Parent Elements</title>
        <para>
          <link linkend="e_global">GLOBAL</link>
        </para>
      </important>
      <important>
        <title>Child Elements</title>
        <para>nothing</para>
      </important>
      <important>
        <title>Attributes</title>
        <variablelist>
          <varlistentry>
            <term><emphasis>scale</emphasis> (type:Float) = 0.01 </term>
            <listitem>
              <para>
                Coefficient of the scale. The value in the ratio.
                (If the default value is used, it scales 1% when mouse wheeled)
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term><emphasis>depth</emphasis> (type:Float) = 0.04 * max(stageWidth,stageHeight)</term>
            <listitem>
              <para>
                Unit of the movement of camera z-coordinate.
                Z position of the camera move this value if mouse wheeled.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </important>
    </section>
    <section id="e_radius">
      <title>RADIUS</title>
      <important>
        <title>Description</title>
        <para><emphasis>Level: </emphasis>3rd</para>
        <para>
          This parameter defines the scale for width/radius of primitives.
          If "relative" is used, the radius/width of primitives such as ATOMs
          are scaled to fit the window size.
          If "absolute" is used, the radius/width of primitives are scaled
          with a constant value spcified by <emphasis>scale</emphasis> below.
        </para>
      </important>
      <important>
        <title>Parent Elements</title>
        <para>
          <link linkend="e_global">GLOBAL</link>
        </para>
      </important>
      <important>
        <title>Child Elements</title>
        <para>nothing</para>
      </important>
      <important>
        <title>Attributes</title>
        <variablelist>
          <varlistentry>
            <term><emphasis>method</emphasis> (type:String) = "relative"</term>
            <listitem>
              <para>
                The way to determine radius. See also <emphasis>scale</emphasis> below.
              </para>
              <para>
                "absolute" : use given <emphasis>scale</emphasis> value below.
              </para>
              <para>
                "relative" : scale the position using the factor <emphasis>scale</emphasis> and stage size/width.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
        <variablelist>
          <varlistentry>
            <term><emphasis>scale</emphasis> (type:Float) = "0.05"</term>
            <listitem>
              <para>
                The scale factor for width/radius.
                In case of "relative", actual scaling factor is
                (this value) * min( stageWidth, stageHeight ).
                In case of "absolute", this value is used as the scaling factor.
                The default value is extermely small for the "absolute" setting.
                If you use "absolute", please modify this scaling factor, too.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </important>
    </section>
    <section id="e_scene">
      <title>SCENE</title>
      <important>
        <title>Description</title>
        <para><emphasis>Level: </emphasis>2nd</para>
        <para>
          A scene. The unit of the view.
        </para>
      </important>
      <important>
        <title>Parent Elements</title>
        <para>
          <link linkend="e_wmxml">WMXML</link>
        </para>
      </important>
      <important>
        <title>Child Elements</title>
        <para>
          <link linkend="e_local">LOCAL</link>,
          <link linkend="e_atom">ATOM</link>,
          <link linkend="e_bond">BOND</link>,
          <link linkend="e_label">LABEL</link>,
          <link linkend="e_shape">SHAPE</link>,
          <link linkend="e_obj3d">OBJ3D</link>,
          <link linkend="e_chain">CHAIN</link>
        </para>
      </important>
      <important>
        <title>Attributes</title>
          <para>nothing</para>
      </important>
    </section>
    <section id="e_local">
      <title>LOCAL</title>
      <important>
        <title>Description</title>
        <para><emphasis>Level: </emphasis>3rd</para>
        <para>
          Local setting for this SCENE. This setting is effective only in
          the parent SCENE.
          Some parameters are inherited from the global setting,
          <link linkend="e_global">GLOBAL</link>.
        </para>
      </important>
      <important>
        <title>Parent Elements</title>
        <para>
          <link linkend="e_scene">SCENE</link>
        </para>
      </important>
      <important>
        <title>Child Elements</title>
        <para>
          <link linkend="e_atom">ATOM</link>,
          <link linkend="e_bond">BOND</link>,
          <link linkend="e_ribbon">RIBBON</link>,
          <link linkend="e_coil">COIL</link>,
          <link linkend="e_shape">SHAPE</link>,
          <link linkend="e_obj3d">OBJ3D</link>,
          <link linkend="e_label">LABEL</link>,
          <link linkend="e_autoscale">AUTOSCALE</link>
        </para>
        <para>
          ATOM, BOND, RIBBON, COIL, SHAPE, OBJ3D, LABEL elements are the LOCAL
          default setting of these primitives. The settings such as color,
          radius here define the default in the parent SCENE.
        </para>
      </important>
      <important>
        <title>Attributes</title>
        <variablelist>
          <varlistentry>
            <term><emphasis>origin</emphasis> (type:<link linkend="ss_point3d">Point3D</link>) = null</term>
            <listitem>
              <para>
                Origin of the coordinate. If you want to predefine the
                geometric center, please add the position.
                If the value is null, the origin is automatically determined.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
        <variablelist>
          <varlistentry>
            <term><emphasis>bg</emphasis> (type:<link linkend="ss_color">Color</link>) = "0x000000"</term>
            <listitem>
              <para>
                Background color. See
                <link linkend="ss_color">Color specification</link>
                for detail about colors.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </important>
    </section>
    <section id="e_autoscale">
      <title>AUTOSCALE</title>
      <important>
        <title>Description</title>
        <para><emphasis>Level: </emphasis>3rd or 4th</para>
        <para>
          Autoscale handler. Usually, the positions of atoms are scaled so
          as to fit the window size.
        </para>
      </important>
      <important>
        <title>Parent Elements</title>
        <para>
          <link linkend="e_global">GLOBAL</link>
          <link linkend="e_local">LOCAL</link>
        </para>
      </important>
      <important>
        <title>Child Elements</title>
        <para>nothing</para>
      </important>
      <important>
        <title>Attributes</title>
        <variablelist>
          <varlistentry>
            <term><emphasis>manual</emphasis> (type:Int) = "0"</term>
            <listitem>
              <para>
                Handler for the position scaling.
                If the value > 0, automatic scaling is disabled and the
                value <emphasis>manualscale</emphasis> (see below) is used
                as the scaling factor. Otherwise (including default), the
                positions are automatically scaled using the
                <emphasis>autoscale</emphasis> parameter and stage size.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
        <variablelist>
          <varlistentry>
            <term><emphasis>autoscale</emphasis> (type:Float) = "0.3"</term>
            <listitem>
              <para>
                Scaling factor for the positions.
                Actual scaling factor is
                stageWidth * (this value) / (largest abs(x) in xml),
                where the geometric center of the coordinate is translated
                to be (0,0,0) automatically.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
        <variablelist>
          <varlistentry>
            <term><emphasis>manualscale</emphasis> (type:Float) = "100.0"</term>
            <listitem>
              <para>
                Positional scaling factor for the manual scaling.
                See also <link linkend="e_radius">RADIUS element</link> if
                you use this.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
        <variablelist>
          <varlistentry>
            <term><emphasis>inherit</emphasis> (type:Int) = "1"</term>
            <listitem>
              <para>
                <emphasis>This parameter is available only inside the <link linkend="e_global">GLOBAL</link>.</emphasis>
                If the value > 0, scaling factor for the positions of the
                first SCENE is inheritted to the other SCENEs.
                Usually, this parameter should not be changed.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </important>
    </section>
    <section id="e_atom">
      <title>ATOM</title>
      <important>
        <title>Description</title>
        <para><emphasis>Level: </emphasis>3rd or 4th</para>
        <para>
          An Atom. An Atom is drawn in sphere.
        </para>
      </important>
      <important>
        <title>Parent Elements</title>
        <para>
          <link linkend="e_global">GLOBAL</link>
          <link linkend="e_scene">SCENE</link>
          <link linkend="e_local">LOCAL</link>
        </para>
      </important>
      <important>
        <title>Child Elements</title>
        <para>nothing</para>
      </important>
      <important>
        <title>Attributes</title>
        <para>
          See also the <link linkend="e_common_attributes">common attributes for primitives</link>.
          Most options such as radius, color are described there.
        </para>
        <variablelist>
          <varlistentry>
            <term><emphasis>pos</emphasis> (type:<link linkend="ss_point3d">Point3D</link>) </term>
            <listitem>
              <para>
                Position of the atom. This parameter is ignored if the ATOM
                is a child element of LOCAL or GLOBAL.
                If the ATOM is a child element of SCENE, this attribute MUST BE
                GIVEN.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </important>
    </section>
    <section id="e_bond">
      <title>BOND</title>
      <important>
        <title>Description</title>
        <para><emphasis>Level: </emphasis>3rd or 4th</para>
        <para>
          A Bond. Bonds are drawn in cylinders.
        </para>
      </important>
      <important>
        <title>Parent Elements</title>
        <para>
          <link linkend="e_global">GLOBAL</link>
          <link linkend="e_scene">SCENE</link>
          <link linkend="e_local">LOCAL</link>
        </para>
      </important>
      <important>
        <title>Child Elements</title>
        <para>nothing</para>
      </important>
      <important>
        <title>Attributes</title>
        <para>
          See also the <link linkend="e_common_attributes">common attributes for primitives</link>.
          Most options such as radius, color are described there.
        </para>
        <variablelist>
          <varlistentry>
            <term><emphasis>pos0</emphasis> (type:<link linkend="ss_point3d">Point3D</link>)</term>
            <term><emphasis>pos1</emphasis> (type:<link linkend="ss_point3d">Point3D</link>)</term>
            <listitem>
              <para>
                Positions of two bonds temini. Both are REQUIRED only for the
                BOND element of the child element of the SCENE.
                In the LOCAL and GLOBAL, pos0 and pos1 are ignored.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term><emphasis>exclude (abbr.:exc)</emphasis> (type:Int) = "0"</term>
            <listitem>
              <para>
                If the value is greater than 0, the top and bottom faces are
                omitted. May not be used usually.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term><emphasis>rounded (abbr.:round)</emphasis> (type:Int) = "1"</term>
            <listitem>
              <para>
                If the value is greater than 0, the top and bottom faces are
                drawn in the half-sphere. This is the default.
                This default is somewhat costly, since many polygons are
                required in drawing half-spheres.
                If you want to reduce the number of polygons, please reset this
                value to 0.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term><emphasis>dashed (abbr.:dash)</emphasis> (type:Int) = "0"</term>
            <listitem>
              <para>
                If the value is greater than 0, the cylinder is drawn in
                (value + 1) dashes. Note that each dash except the terminus ones
                does not have both bottom and top faces. Terminus ones has
                only one of them.
              </para>
              <para>
                In the future versions, top and bottom faces will be added to
                the intermediate dashes.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </important>
    </section>
    <section id="e_ribbon">
      <title>RIBBON</title>
      <important>
        <title>Description</title>
        <para><emphasis>Level: </emphasis>3rd, 4th, or 5th</para>
        <para>
          A ribbon. A ribbon is drawn with a smoothly curved plane.
          Thickness of the plane is also changeable.
        </para>
      </important>
      <important>
        <title>Parent Elements</title>
        <para>
          <link linkend="e_global">GLOBAL</link>,
          <link linkend="e_local">LOCAL</link>,
          <link linkend="e_chain">CHAIN</link>
        </para>
      </important>
      <important>
        <title>Child Elements</title>
        <para>nothing</para>
      </important>
      <important>
        <title>Attributes</title>
        <para>
          See also the <link linkend="e_common_attributes">common attributes for primitives</link>.
          Most options such as radius, color are described there.
        </para>
        <variablelist>
          <varlistentry>
            <term><emphasis>init</emphasis> (type:Int) </term>
            <term><emphasis>last</emphasis> (type:Int) </term>
            <listitem>
              <para>
                Initial and last index in chain.
                The "last" value must be bigger than "init", and the
                <link linkend="e_point">POINT</link> having the values
                init-last must exist. See POINT element for further
                information.
                These value are ignored in LOCAL and GLOBAL, but are REQUIRED
                in CHAIN.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term><emphasis>thickness (abbr.:thick)</emphasis> (type:Float) = "0.0"</term>
            <listitem>
              <para>
                Thickness of the ribbons.
                (This setting is also valid in LOCAL and GLOBAL)
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </important>
    </section>
    <section id="e_coil">
      <title>COIL</title>
      <important>
        <title>Description</title>
        <para><emphasis>Level: </emphasis>3rd, 4th, or 5th</para>
        <para>
          A coil. Coils are drawn in tubes.
        </para>
      </important>
      <important>
        <title>Parent Elements</title>
        <para>
          <link linkend="e_global">GLOBAL</link>,
          <link linkend="e_local">LOCAL</link>,
          <link linkend="e_chain">CHAIN</link>,
        </para>
      </important>
      <important>
        <title>Child Elements</title>
        <para></para>
      </important>
      <important>
        <title>Attributes</title>
        <para>
          See also the <link linkend="e_common_attributes">common attributes for primitives</link>.
          Most options such as radius, color are described there.
        </para>
        <variablelist>
          <varlistentry>
            <term><emphasis>init</emphasis> (type:Int) </term>
            <term><emphasis>last</emphasis> (type:Int) </term>
            <listitem>
              <para>
                Initial and last index in chain.
                The "last" value must be bigger than "init", and the
                <link linkend="e_point">POINT</link> having the values
                init-last must exist. See POINT element for further
                information.
                These value are ignored in LOCAL and GLOBAL, but are REQUIRED
                in CHAIN.
              </para>
              <para>
                These attributes are the same as those in
                <link linkend="e_ribbon">RIBBON</link>s.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </important>
    </section>
    <section id="e_obj3d">
      <title>OBJ3D</title>
      <important>
        <title>Description</title>
        <para><emphasis>Level: </emphasis>3rd or 4th</para>
        <para>
          General objects such as Cones, Cubes, Cylinders, and Squares.
          These objects can be used to generate a shape such as
          arrows( cone + cylinder ).
        </para>
      </important>
      <important>
        <title>Parent Elements</title>
        <para>
          <link linkend="e_global">GLOBAL</link>,
          <link linkend="e_local">LOCAL</link>,
          <link linkend="e_scene">SCENE</link>
        </para>
      </important>
      <important>
        <title>Child Elements</title>
        <para>nothing</para>
      </important>
      <important>
        <title>Attributes</title>
        <para>
          See also the <link linkend="e_common_attributes">common attributes for primitives</link>.
          Most options such as radius, color are described there.
        </para>
        <variablelist>
          <varlistentry>
            <term><emphasis>type</emphasis> (type:String) = "cone" </term>
            <listitem>
              <para>
                Object type. Available types are "cone", "cube", "cylinder",
                and "square".
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term><emphasis>pos</emphasis> (type:<link linkend="ss_point3d">Point3D</link>)</term>
            <listitem>
              <para>
                Position of the object. REQUIRED if it is the child element
                of a SCENE. In other cases, this attribute is simply ignored.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term><emphasis>dir</emphasis> (type:<link linkend="ss_point3d">Point3D</link>) = null </term>
            <listitem>
              <para>
                Direction of the object. If the value is not null,
                the object looks towards the specified direction.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term><emphasis>x</emphasis> (type:Float) = "0.0", </term>
            <term><emphasis>y</emphasis> (type:Float) = "0.0", </term>
            <term><emphasis>z</emphasis> (type:Float) = "0.0" </term>
            <listitem>
              <para>
                The meaning of these parameters depends on the object type.
                For "cube", these three values are used as the box length.
                For "cone" and "cylinder", "x" is used as the radius of the
                bottom face and "y" is used as the height of the cone/cylinder.
                For "square", "x" and "y" are used as the lengths of the square.
                In case of "cone" and "cylinder", "radius" can also be used as
                "x" but attribute "x" overwrites the "radius" setting.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </important>
    </section>
    <section id="e_label">
      <title>LABEL</title>
      <important>
        <title>Description</title>
        <para><emphasis>Level: </emphasis>3rd or 4th</para>
        <para>
          A text label. The position of the text can change by rotation,
          though the text itself does not rotate.
        </para>
      </important>
      <important>
        <title>Parent Elements</title>
        <para>
          <link linkend="e_global">GLOBAL</link>
          <link linkend="e_local">LOCAL</link>
          <link linkend="e_scene">SCENE</link>
        </para>
      </important>
      <important>
        <title>Child Elements</title>
        <para>nothing</para>
      </important>
      <important>
        <title>Attributes</title>
        <para>
          See also the <link linkend="e_common_attributes">common attributes for primitives</link>.
          Most options such as radius, color are described there.
        </para>
        <variablelist>
          <varlistentry>
            <term><emphasis>pos</emphasis> (type:<link linkend="ss_point3d">Point3D</link>)</term>
            <listitem>
              <para>
                Position of the Label. REQUIRED if this is the child element of
                a SCENE.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term><emphasis>text</emphasis> (type:String)</term>
            <listitem>
              <para>
                Label text. REQUIRED if this is the child element of a SCENE.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term><emphasis>font</emphasis> (type:String) = "Arial"</term>
            <listitem>
              <para>
                Font name.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term><emphasis>fontsize</emphasis> (type:Float) = "32.0"</term>
            <listitem>
              <para>
                Font size in pixel.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </important>
    </section>
    <section id="e_shape">
      <title>SHAPE</title>
      <important>
        <title>Description</title>
        <para><emphasis>Level: </emphasis>3rd or 4th</para>
        <para>
          A shape is constructed by triangles.
          This will enable users to draw various kinds of objects such as
          mathematical functions, molecular orbitals, and molecular surfaces.
          Positions of polygons are determined by child elements, TRIs.
        </para>
      </important>
      <important>
        <title>Parent Elements</title>
        <para>
          <link linkend="e_global">GLOBAL</link>,
          <link linkend="e_local">LOCAL</link>,
          <link linkend="e_scene">SCENE</link>
        </para>
      </important>
      <important>
        <title>Child Elements</title>
        <para>
          <link linkend="e_tri">TRI</link>
        </para>
      </important>
      <important>
        <title>Attributes</title>
        <para>
          See also the <link linkend="e_common_attributes">common attributes for primitives</link>.
          Most options such as radius, color are described there.
        </para>
      </important>
    </section>
    <section id="e_chain">
      <title>CHAIN</title>
      <important>
        <title>Description</title>
        <para><emphasis>Level: </emphasis>3rd</para>
        <para>
          A chain contains a series of POINTs, which is usually atom positions,
          and is used to draw COILs and RIBBONs.
          See <link linkend="e_coil">COIL</link>,
              <link linkend="e_ribbon">RIBBON</link>,
              and <link linkend="e_point">POINT</link> for detail about CHAIN
        </para>
        <para>
          A chain must have at least four POINTs.
          Very short chains with less than four POINTs are simple ignored.
          This limitation comes from the Catmull-Rom method, which is used
          to intepolate POINTs.
        </para>
      </important>
      <important>
        <title>Parent Elements</title>
        <para>
          <link linkend="e_scene">SCENE</link>
        </para>
      </important>
      <important>
        <title>Child Elements</title>
        <para>
          <link linkend="e_ribbon">RIBBON</link>,
          <link linkend="e_coil">COIL</link>,
          <link linkend="e_point">POINT</link>
        </para>
      </important>
      <important>
        <title>Attributes</title>
        <variablelist>
          <varlistentry>
            <term><emphasis>N</emphasis> (type:Int) = 3</term>
            <listitem>
              <para>
                Number of points inserted between adjacent two points with
                Catmull-Rom method.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </important>
    </section>
    <section id="e_point">
      <title>POINT</title>
      <important>
        <title>Description</title>
        <para><emphasis>Level: </emphasis>4th</para>
        <para>
          A point is the component of <link linkend="e_chain">CHAIN</link>.
          This element is used as control points for Catmull-Rom interpolation.
          Users should add at least four points for each CHAIN.
        </para>
        <para>
          If a chain has less than four points,
          wm3d will show a warning message (if trace is enabled).
        </para>
      </important>
      <important>
        <title>Parent Elements</title>
        <para>
          <link linkend="e_chain">CHAIN</link>
        </para>
      </important>
      <important>
        <title>Child Elements</title>
        <para>nothing</para>
      </important>
      <important>
        <title>Attributes</title>
        <variablelist>
          <varlistentry>
            <term><emphasis>pos</emphasis> (type:<link linkend="ss_point3d">Point3D</link>) </term>
            <listitem>
              <para>
                The position of this POINT. This MUST BE SPECIFIED.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term><emphasis>index</emphasis> (type:Int) </term>
            <listitem>
              <para>
                Unique index for this POINT in the chain.
                This MUST BE SPECIFIED, since this index is used in
                in RIBBONs and COILs.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term><emphasis>N</emphasis> (type:Int) = (inherited from CHAIN)</term>
            <listitem>
              <para>
                Number of POINTs to be interpolated between POINTs.
                It is same as "N" in CHAIN.
                Setting here overwrites the setting of this CHAIN.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </important>
    </section>
    <section id="e_tri">
      <title>TRI</title>
      <important>
        <title>Description</title>
        <para><emphasis>Level: </emphasis>4th</para>
        <para>
          A tri describes a triangle.
          Two triangles, front and back faces, are created from a TRI element.
          Color and alpha of TRIs are determined in the parent SHAPE element.
        </para>
      </important>
      <important>
        <title>Parent Elements</title>
        <para>
          <link linkend="e_shape">SHAPE</link>
        </para>
      </important>
      <important>
        <title>Child Elements</title>
        <para>nothing</para>
      </important>
      <important>
        <title>Attributes</title>
        <variablelist>
          <varlistentry>
            <term><emphasis>p0, p1, p2</emphasis> (type:<link linkend="ss_point3d">Point3D</link>)</term>
            <listitem>
              <para>
                Positions of the triangle vertexes. All these three values
                MUST BE SPECIFIED.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </important>
    </section>
    <section id="e_common_attributes">
      <title>common attributes for primitives</title>
      <important>
        <title>Description</title>
        <para>
          Common attributes for ATOMs, BONDs, COILs, RIBBONs, SHAPEs, OBJ3Ds,
          and LABELs.
        </para>
      </important>
      <important>
        <title>Attributes</title>
        <variablelist>
          <varlistentry>
            <term><emphasis>width (abbr.:w) </emphasis> (type:Float)</term>
            <listitem>
              <para>
                width/radius of the object.
                It is radius for ATOM(sphere), BOND(cylinder), COIL(tube), and
                is width for RIBBON(curved plane).
                In LABELs, this parameter is used as the textfield size.
                This attribute might be more important than "fontsize".
                In SHAPEs, this parameter is not used and is simply ignored.
                In OBJ3Ds, the meaning depends on its type. See <link linkend="e_obj3d">OBJ3D</link>.
              </para>
              <para><emphasis>Defaults:</emphasis></para>
              <para>
                ATOM : 4.0, BOND : 3.0, COIL : 3.0, RIBBON : 8.0, LABEL : 130.0, OBJ3D : 1.0
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term><emphasis>radius (abbr.:r) </emphasis> (type:Float)</term>
            <listitem>
              <para>
                alias to width above
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term><emphasis>color (abbr.:c) </emphasis> (type:<link linkend="ss_color">Color</link>)</term>
            <listitem>
              <para>
                Color of the object or the text.
              </para>
              <para><emphasis>Defaults:</emphasis></para>
              <para>
                ATOM : 0x00FF00 (lime),
                BOND : 0x00FF00 (lime),
                COIL : 0x00FF00 (lime),
                RIBBON : 0xFF0000 (red),
                LABEL : 0xFFFFFF (white),
                SHAPE : 0x00FF00 (lime),
                OBJ3D : 0x00FF00 (lime)
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term><emphasis>color0 (abbr.:c0,col0) </emphasis> (type:<link linkend="ss_color">Color</link>), </term>
            <term><emphasis>color1 (abbr.:c1,col1) </emphasis> (type:<link linkend="ss_color">Color</link>)</term>
            <listitem>
              <para>
                For BONDs, COILs, and RIBBONs, objects can be drawn using two
                colors if you specify these two variables.
                In BONDs, one side of the cylinder is painted with color0, 
                and the other side is painted with color1.
                In COILs and RIBBONs, the object is drawn in the gradation of
                these two colors.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term><emphasis>alpha (abbr.:a) </emphasis> (type:Float)</term>
            <listitem>
              <para>
                Alpha value ranging 0.0(transparent)-1.0(opaque).
                The default value is 1.0 for all the primitives.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term><emphasis>quality (abbr.:q,qua) </emphasis> (type:Int)</term>
            <listitem>
              <para>
                Quality of the object.
                Increasing the quality increases the number of polygons for
                this object.
                This attribute is available for ATOMs, BONDs, COILs, and OBJ3Ds.
                Too large quality is not recommended.
              </para>
              <para><emphasis>Defaults:</emphasis></para>
              <para>
                ATOM : 3,
                BOND : 2 (pentagon),
                COIL : 0 (triangle pole),
                OBJ3D : 3,
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term><emphasis>ambient (abbr.:am,amb) </emphasis> (type:Float)</term>
            <listitem>
              <para>
                Intensity of ambient for Gouraud and Phong shadings.
                The color of ambient is the same as "color" above.
                White-colored ambient is not implemented.
                This attribute is ignored for LABELs.
                The value should be 0.0-1.0.
                Too large value will make the scene very whity.
              </para>
              <para><emphasis>Defaults:</emphasis></para>
              <para>
                ATOM : 0.35,
                BOND : 0.3,
                COIL : 0.3,
                RIBBON : 0.3,
                SHAPE : 0.3,
                OBJ3D : 0.35
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term><emphasis>diffuse (abbr.:d,dif,diff) </emphasis> (type:Float)</term>
            <listitem>
              <para>
                Intensity of diffuse for Gouraud and Phong shadings.
                This attribute is ignored for LABELs.
                The value should be 0.0-1.0.
              </para>
              <para><emphasis>Defaults:</emphasis></para>
              <para>
                ATOM : 0.7,
                BOND : 1.0,
                COIL : 0.7,
                RIBBON : 0.7,
                SHAPE : 0.5,
                OBJ3D : 0.7
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term><emphasis>diffuse (abbr.:d,dif,diff) </emphasis> (type:Float)</term>
            <listitem>
              <para>
                Intensity of diffuse for Gouraud and Phong shadings.
                This attribute is ignored for LABELs.
                The value should be 0.0-1.0.
              </para>
              <para><emphasis>Defaults:</emphasis></para>
              <para>
                ATOM : 0.7,
                BOND : 1.0,
                COIL : 0.7,
                RIBBON : 0.7,
                SHAPE : 0.5,
                OBJ3D : 0.7
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term><emphasis>specular (abbr.:s,spe,spec) </emphasis> (type:Float)</term>
            <listitem>
              <para>
                Intensity of specular for Phong shading.
                Half vector of the light direction and the camera direction is
                used as the reflection direction.
                This attribute is ignored for LABELs.
                The value should be 0.0-1.0.
              </para>
              <para><emphasis>Defaults:</emphasis></para>
              <para>
                ATOM : 0.8,
                BOND : 0.6,
                COIL : 0.8,
                RIBBON : 0.8,
                SHAPE : 0.2,
                OBJ3D : 0.8
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term><emphasis>gloss (abbr.:g) </emphasis> (type:Float)</term>
            <listitem>
              <para>
                Specular gloss of Phong shading.
                This attribute is ignored for LABELs.
              </para>
              <para><emphasis>Defaults:</emphasis></para>
              <para>
                ATOM : 20.0,
                BOND : 20.0,
                COIL : 10.0,
                RIBBON : 10.0,
                SHAPE : 20.0,
                OBJ3D : 20.0
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term><emphasis>shading (abbr.:shade,shader) </emphasis> (type:String)</term>
            <listitem>
              <para>
                Shading method.
                Valid entries are "simple", "gouraud", and "phong".
                "Simple" never consider lights and is very light-weighted.
                "Gouraud" is a popular gouraud shading, ambient and diffuse
                are considered.
                In "phong", specular reflection is also considered.
                This attribute is ignored for LABELs.
                The default is "phong" for all the primitives.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </important>
    </section>
  </chapter>
  <chapter id="c_nonstandard">
    <title>Non-standard function</title>
    <para>
      not yet
    </para>
  </chapter>
  <chapter id="c_sample_xml">
    <title>Sample XML</title>
    <para>
      There are some sample XML files and compiled SWF files in the
      wm3d-(version)/src/samples directory of the distribution.
      These samples will cover most of the standard usages.
    </para>
  </chapter>
</book>
