# LScript v2.4 Release Notes

## New Features

      A Layout object's world rotation values can now be calculated using the new WROTATION
      param() method flag, or the new getWorldRotation() method.  If the object is unparented,
      then WROTATION/getWorldRotation() returns a value equivalent to ROTATION/getRotation().
      The ctlpage() Requester function now accepts an array of Control Object Agents in
      addition to a comma-separated list.  The array reference must be the second and last
      argument to the function.
      A new control type called ctlmenu() has been added to the Requester mechanism.  This
      control type consists of a button that displays a popup menu when pressed.

      The first argument is the title of the button.  Next, a list of the items that will
      appear on the menu when displayed.  As with ctlpopup(), this list can be an array
      reference or an initialization block of values.  A required callback function is then
      defined to process any selections made from the menu.  A fourth optional argument will
      define a callback used to enable/disable individual menu entries.

      A special entry value is recognized as a menu separator.  An entry that begins with
      at least two equal signs (=) will cause a separator to be added to the popup menu
      at the indicated location.

      The menu value returned to either callback function corresponds directly to the linear
      value of the entry in the original items.  However, separator entries will never be
      processed.

            @version 2.4
            @warnings

            menu_items = @"New Session","Close Session","=====","Quit"@;

            generic
            {
                reqbegin("Testing");
                c1 = ctlmenu("Sessions",menu_items,"menu_select","menu_active");

                reqpost();
                reqend();
            }

            menu_select: item
            {
                info("You selected '",menu_items[item],"'");
            }

            menu_active: item
            {
                return(item != 2);
            }
      Two new Requester functions, drawtextwidth() and drawtextheight(), have been added to
      determine the display width and height, in pixels, of a text string.  They each take
      a single character string, and return an integer value representing this pixel width
      or height.
      A new information display control is available to Requesters.  Created with ctlinfo(),
      it defines an area on the Requester panel into which subsequent drawing will occur
      when a specified UDF callback is invoked.  All drawing into this area is clipped by
      LScript.

      Three arguments are required by the ctlinfo() function.  The first two are integer values
      that specify the width and height of the display area.  The third argument defines
      the UDF to be called when the informational area needs to be redrawn.  This UDF takes
      no arguments, and has access to all the Requester redraw functions (drawtext(),
      drawpixel(), etc.).

            @version 2.4
            @warnings

            @define MSG     "This is cool!"

            msg_x = 101;

            generic
            {
                reqbegin("Testing");
                c1 = ctlinfo(100,30,"info_redraw");

                reqpost("marquee",50);
                reqend();
            }

            info_redraw
            {
                drawbox(<132,130,132>,0,0,100,30);
                if(msg_x > 100)
                    msg_x = -1 * drawtextwidth(MSG);
                drawtext(MSG,<0,0,0>,msg_x, integer((30 - drawtextheight(MSG)) / 2));
                drawborder(0,0,100,30,true);
            }

            marquee
            {
                msg_x += 2;
                requpdate();
            }
      Several new surface-related Object Agents are available in LScript, the first of which
      is the Surface Object Agent, from which all others are derived.  The Surface() constructor
      can be used to generate an Object Agent for an existing surface, or it can be used to
      create a new surface for an object.

      The constructor can be called with no arguments, and the first surface defined in the
      system will be returned.

      If called with an integer value, the surface in the system that corresponds to that
      index value will be returned.

      Provided a surface name, the constructor will return that surface if it is already
      defined in the system.  If it does not exist, a 'nil' value will be returned under Layout,
      and a new surface with that name will be generated for the current object under Modeler.

      Provided a Mesh Object Agent, a list of the surface names defined for that object will
      be returned.

      Under Layout, you can create a new surface for an object by providing the Mesh Object
      Agent to receive the surface as the first argument, and the name of the surface as the
      second.

      The following channel constants have been defined in LScript for use with the Surface
      Object Agent:

            SURFCOLR            Base Color              (vector)
            SURFLUMI            Luminosity              (number)
            SURFDIFF            Diffuse                 (number)
            SURFSPEC            Specularity             (number)
            SURFREFL            Reflectivity            (number)
            SURFTRAN            Transparency            (number)
            SURFTRNL            Translucency            (number)
            SURFRIND            IOR                     (number)
            SURFBUMP            Bump                    (number)
            SURFGLOS            Glossiness              (number)
            SURFBUF1            Special Buffer 1        (number)
            SURFBUF2            Special Buffer 2        (number)
            SURFBUF3            Special Buffer 3        (number)
            SURFBUF4            Special Buffer 4        (number)
            SURFSHRP            Diffuse Sharpness       (number)
            SURFSMAN            Smoothing Angle         (degrees)
            SURFRSAN            Reflection Seam Angle   (degrees)
            SURFTSAN            Refraction Seam Angle   (degrees)
            SURFRBLR            Reflection Blur         (number)
            SURFTBLR            Refraction Blur         (number)
            SURFCLRF            Color Filter            (number)
            SURFCLRH            Color Highlights        (number)
            SURFADTR            Additive Transparency   (number)
            SURFAVAL            Alpha Value             (number)
            SURFGVAL            Glow Value              (number)
            SURFLCOL            Line Color              (vector)
            SURFLSIZ            Line Size               (number)
            SURFSIDE            Sidedness               (integer)
            SURFGLOW            Glow                    (Boolean)
            SURFLINE            Render Outlines         (Boolean)
            SURFRIMG            Reflection Image        (Image Object Agent)
            SURFTIMG            Refraction Image        (Image Object Agent)
            SURFVCOL            Vertex Coloring         (number)

      The following data members are exported by the Surface Object Agent:

            name
                    the name of the surface

      The following methods are available:

            getValue(<channel>)

                    returns the specific value setting for the channel (whose type is
                    defined above).

            getEnvelope(<channel>)

                    returns the Envelope Object Agent associated with the specified
                    channel.  returns 'nil' if none exists.

            getTexture(<channel>)

                    returns the Texture Object Agent (documented below) associated
                    with the specified channel.  returns 'nil' if none exists.
      A Texture Object Agent can be generated from the Surface Object Agent (using its
      getTexture() method).  This Object Agent provides an interface to a texture assigned
      to a specific channel in a surface.  Textures have their own settings, including one or
      more layers that accumulate to represent the visual makeup of the surface.

      The following texture constants have been defined in LScript for use with the Texture
      Object Agent:

            TXTRIMAGE           Image Texture type
            TXTRPROCEDURE       Procedural Texture type
            TXTRGRADIENT        Gradient Texture type

      The following methods are exported by the Object Agent:

            setChannelGroup(<Channel Group Object Agent>)

                    sets the Texture's channel group using the provided Object Agent.
                    Envelopes created for parameters in the Texture's layers will
                    belong to this group.

            getChannelGroup()

                    returns the Channel Group Object Agent for the Texture.

            firstLayer()

                    returns the TextureLayer Object Agent (documented below) for the
                    first layer defined in the Texture.

            nextLayer(<TextureLayer Object Agent>)

                    returns the TextureLayer Object Agent that follows the
                    specified TextureLayer for the Texture.

            addLayer(<layer type>)

                    creates a new layer in the Texture of the specific type--one,
                    of TXTRIMAGE, TXTRPROCEDURE or TXTRGRADIENT--and returns the
                    TextureLayer Object Agent for it.
      A TextureLayer Object Agent is generated by the Texture Object Agent, and serves as
      proxy for the settings for the each layer defined in the Texture.

      The following channel constants have been defined in LScript for use with the
      TextureLayer Object Agent:

            TXLRPOSITION        Position                (vector)
            TXLRROTATION        Rotation                (vector)
            TXLRSIZE            Size                    (vector)
            TXLRFALLOFF         Falloff                 (vector)
            TXLRPROJECT         Projection              (constant)
            TXLRAXIS            Texture Axis            (integer)
            TXLRWWRAP           Width Wrap              (number)
            TXLRHWRAP           Height Wrap             (number)
            TXLRCOORD           Coordinate System       (integer: 1==object, 2==world)
            TXLRIMAGE           Image                   (Image Object Agent)
            TXLRVMAP            VMap                    (VMap Object Agent)
            TXLREFOBJ           Reference Object        (Layout Object Agent)
            TXLROPACITY         Opacity                 (number)
            TXLRANTIALIAS       Antialias               (Boolean)
            TXLRAAVALUE         Antialias Threshold     (number)
            TXLRPIXBLEND        Pixel Blending          (Boolean)
            TXLRWREPEAT         Width Repeat            (constant)
            TXLRHREPEAT         Height Repeat           (constant)

      The defined constants for a texture's TXLRPROJECT setting are:

            TXPJPLANAR
            TXPJCYLINDRICAL
            TXPJSPHERICAL
            TXPJCUBIC
            TXPJFRONT
            TXPJUVMAP

      The defined constants for a texture's TXLRWREPEAT and TXLRHREPEAT settings are:

            TXRPRESET
            TXRPREPEAT
            TXRPMIRROR
            TXRPEDGE

      The following data members are exported by the TextureLayer Object Agent:

            type
                    the type of the layer (TXTRIMAGE, TXTRPROCEDURE or TXTRGRADIENT)

      The following methods are available:

            getValue(<channel>)

                    retrieves the value of the specified channel in the layer.

            setValue(<channel>,<value>)

                    sets the the specified layer channel to the provided value.
      Layout Object Agents now provide methods for managing each object's scene tag information.

      The getTag() method takes an integer index value, and returns the tag value for that index,
      or 'nil' is no tag exists.

      The setTag() method take an index value, and a string tag value, and applies it to the
      object.  When the current scene is saved, the tag information will be stored into the
      scene file in association with the object.

## Behavioral Changes

      The ctltext() Requester function has been augmented to accept an Array reference as either
      the first (and only) argument, or the second (and final) from which text strings will be
      extracted.
      The requpdate() function now triggers a redraw in any visible ctlinfo() area.
      The drawborder() Requester redraw function now accepts a fifth optional Boolean argument
      that indicates the indentation of the border to be drawn.  If omitted (or false), then
      the border is draw with a "raised" look.   If true, then the border has a "sunken" look.
      The ctlactive() and ctlvisible() Requester functions have been augmented to accept an
      Array of Control identifiers as the third (and final) argument.
      The "Ok" button, and the button area, has been removed from non-modal Requester
      panels to futher integrate scripts with the overall LightWave look-and-feel.

## Bug Fixes

      A memory leak existed in the code that processes the points[] Object Agent data
      member reference.  The leak did not involve memory allocated by LScript, and so
      was not released when the script terminated.
      The Requester key handling had a bug that could crash the application under certain
      circumstances.
      The LScript pre-processor was unaware of the fact that the script it was processing
      was simply being installed instead of executed.  This made the pre-processor enforce
      certain pragma directives at inappropriate times.
      The Layout LScript compiler was not setting an internal architecture flag before
      compiling the specified script, leading to a loss of architecture-specific constant
      definitions in the output file.  This lack of definition caused operational
      anomalies with the Layout LScript run-time system.
      The Control identifier type, while housed well within an array, was not being
      properly identified by LScript when accessed as an array element.
      LScript's Requester mechanism was not correctly handling situations where an open
      panel launches another.
      The Particle Object Agent was not being handled properly in all cases involving
      array duplication.
      Non-modal windows would not re-open again once closed because LScript was confused
      about the fact that it had actually been closed.
      Controls generated by the ctltext() function were not functioning properly with the
      visible() method.
      The ommission of an "else" in LScript's code made it impossible to access any of
      the Custom Object Agent's data members.
      Internal switching problems were occurring with requester panels, leading to crashes
      L-value expressions (those on the left of an assignment) involving arrays were not
      being flagged correctly by LScript, leading to evaluation failure (and possibly a
      crash).
      Associative array handling could cause a crash when an assignment was attempted on
      an array not already flagged as associative.