MODELER AREXX INTERFACE ======================= Updated 5/93 Modeler operates as a function host for functions only. IT NO LONGER ACCEPTS COMMAND FORM MESSAGES. "LWModelerARexx.port" is the function host address. Proposed but not implemented interfaces are marked with "@". NOTICE: This interface specification is subject to change at any time up to the release of the final product. FUNCTION ARGUMENTS Function arguments and return values are generally one of the fixed set of types whose formats are listed below, although values may be formatted in a specific way for some functions. The standard formats are shown here: number -- a floating point or integer number. examples: 12 -99 0 1.23 -.5601 1.667e-3 bool -- a number where 0 is false and anything else is true (usually 1). vector -- a triple of floating point numbers separated by spaces, or a single number. A single number is interpreted as a vector with all three components the same. examples: 1 1 -1 .5 -12.6 0 0 -15 -13 example: 2 and 2 2 2 give the same vector string -- raw argument text keyword -- one of several possible keywords, shown as (a|b|c...) Only enough of a keyword need be specified to distinguish it from the other possibilities. example: axis (X|Y|Z) layers -- a list of one or more layer numbers in the range 1-8. INTERFACE MODES and STATES The client ARexx interface has modes and states in which it operates. Some commands are only valid in some modes, and some are valid in any mode. An attempt to use a command when the interface is in the wrong mode will generate an error. NORMAL mode. This is the default mode, and the one the interface starts in. Most single-function commands are valid in this mode. ADD mode. Started with ADD_BEGIN and exited with ADD_END. Only the "add" data creation commands are allowed in this mode. TRANSFORM mode. Started with XFRM_BEGIN and ended with XFRM_END. Only "xfrm" coordinate trasform commands are allowed in this mode. REPLICATE mode. Started with REPL_BEGIN and ended with REPL_END. Only replication step commands are allowed in this mode. Any of the above modes will also be terminated with a BEGIN command for another of the modes, or the END_ALL command. In addition to these mutually-exclusive modes, there is the REQUESTER state, which is used to build and display a requester to the user for input. This additional mode is entered and exited with REQ_BEGIN and REQ_END commands. The "req" requester commands are only valid in REQUESTER state, but other commands, including the mode change commands above are valid regardless of REQUESTER state. FUNCTION SUMMARY Parameter types are shown in <>'s. Trailing arguments which are optional are shown in []. General: NEW() -- Clear all data. EXIT() -- Return to LightWave layout. There can be no commands after this one. UNDO() -- Restore data from last change. CUT() -- Cut current layers to paste buffer. COPY() -- Copy current layers to paste buffer. PASTE() -- Copy paste buffer to current layer. File I/O: LOAD(filename) -- Load data from LightWave file into current layer. SAVE(filename) -- Store data from current layers into LightWave file. State: SETLAYER() SETBLAYER() -- Switch active or background layers to show given list. SURFACE(name) -- Set current surface to given name. If it does not exist it will be created. END_ALL() -- Set mode to NORMAL regardless of current mode, and terminate REQUESTER state, if active. This is done automatically when a script initiated from Modeler completes. Point Transforms: The "Flex" and "Deform" transformations use similar region data to define the scope of their operations. These are set globally and then applied to all trasformations of a given type. FIXEDFLEX(axis, start, end, [ease]) -- Set the flex functions to operate on a fixed range along an axis. Ease is a string which can contain one or both of 'i' and 'o' for ease-in and/or ease-out. AUTOFLEX(axis, direction<+|->, [ease]) -- Set the flex functions to operate on an automatic range along an axis of the given polarity. DEFORMREGION(radius, [center, [axis]]) -- Set the area of effect for the deformation tools. If axis is omitted, the effect is bounded in all directions by the given radius. If an axis is specified, the effect is unbounded along that axis. MOVE (offset) SHEAR (offset) MAGNET(offset) -- Translate points by the given offset. Shear translates along the flex axis. Magnet translates in the deform region. ROTATE(angle, axis, [center]) TWIST (angle, axis, [center]) VORTEX(angle, axis, [center]) -- Rotate points along the given axis by the angle given in degrees. Twist uses the flex axis, and vortex uses the deform region. SCALE(factor, [center]) TAPER(factor, [center]) POLE (factor, [center]) -- Scale points by the given factors around the given center. Taper uses the flex axis, and pole uses the deform region. BEND(angle, direction, [center]) -- Bend points by the given bend angle in the direction around the optional center. This function uses the current flex axis. JITTER(radius) -- Randomly translate points within a given radius. SMOOTH([iterations, [strength]]) -- Apply smoothing function to attempt to remove kinks in polygons connecting affected points. Object Creation: MAKEBOX(lowcorner, highcorner, [nsegments]) -- Make a box with the given extent and divisions. MAKEBALL(radius, nsides, nsegments, [center]) -- Make a globe-style sphere. MAKETESBALL(radius, level, [center]) -- Make a tesselated sphere. MAKEDISC(radius, top, bottom, axis, nsides, [nsegments, [center]]) -- Make a disc. MAKECONE {same as disc} -- Make a cone. Top is the pointy end. Text: index = FONTLOAD(filename) -- Load the given font file into the font list. Returns the font index in the table if loaded sucessfully, zero otherwise. count = FONTCOUNT() -- Get number of fonts loaded. index = FONTINDEX(name) -- Get index for name. name = FONTNAME(index) -- Get name for index. width = MAKETEXT(text, index) -- Generate text using the given font index. Returns width as computed from the font metrics. Query Functions: active = CURLAYER() -- Returns current layer numbers. empty = EMPTYLAYERS() -- Returns numbers of empty layers. name = CURSURFACE() -- Returns current surface name. boxdata = BOUNDINGBOX([test]) -- Returns bounding box information for the given layers or the current layers if none given. Bounding box is a string: num x0 x1 y0 y1 z0 z1 num is number of points tested. If 0, the remaining values are also zero. The remaining values are the low and high in the three axes -- 0 is low, 1 is high. Additional: LATHE(axis, nsides, [center, [endangle, [startangle]]]) EXTRUDE(axis, extent, [nsegments]) @ AXISDRILL(operation, axis, [surface]) @ SOLIDDRILL(operation, [surface]) BOOLEAN(operation) BEVEL(inset, shift) FLIP() TRIPLE() Data Creation (ADD mode): ADD_BEGIN() -- Enter data creation (ADD) mode. Points and polygons can be added. Other operations are illegal except for the SURFACE command which sets surface for new polygons. index = ADD_POINT(position) -- Points are numbered in creation order starting at 1. The index of the new point is returned. ADD_POLYGON() -- Takes a variable number of point numbers as argument. Polygon is created using current default surface. ADD_QUAD() -- Takes a variable number of point numbers, up to four. Polygon is created using current default surface and will have 2 sides or be made with triangles if those flags are set. ADD_CURVE(, [ccstate]) -- Takes a variable number of point numbers as argument. Curve is assigned current default surface. Ccstate gives the condition of the continuity control points at the start and end. If the ccstate argument contains 's', the first point in the list is a CC point. If the string contains 'e', the same for the last point in list. ADD_END() -- Exit data creation mode. New data will appear in the layer at this time and the whole operation can be undone as an atomic command. Point Transform (TRANSFORM mode): n = XFRM_BEGIN() -- Start a point transformation. Returns number of points in the current layer. Other commands are illegal. pos = XFRM_GETPOS(index) -- Get position of indexed point. Index is from 1 to N. XFRM_SETPOS(index, position) -- Move the indexed point to a new position. XFRM_END() -- Complete the transform and move all the points to their new positions. END_ALL aborts the transform. Sweep and Copy (REPLICATE mode): REPL_BEGIN(mode) -- Start replication. This is a copy or sweep, given by the argument. REPL_STEP(offset, scale, rotation, [center]) -- Set the next step of the replication. Offset is a shift. Rotation is a vector of (H,P,B) which is rotation around the Y, X and Z axes, respectively. Rotation and scaling will occur around optional center. To get a first step that is the same as the start pattern, REPL_STEP(0) must be used. REPL_END() -- Complete the replication creating new data. END_ALL can be used to abort the operation. Selection: Selection can be in two modes. In the GLOBAL mode, all points and polygons in active layers are selected for operation. This is the default selection mode. In USER mode, the selection set in the main window is honored by rexx functions. This selection can also be altered. SEL_MODE(newmode) -- Set the selection mode. END_ALL or script termination will reset this mode to GLOBAL. SEL_POINT(action, [condition ...]) -- Modify point selection. Only valid in USER mode, and the user's selection mode will be changed to point if it is not already. If there is no condition, the action will apply to all points. Otherwise, the points specified by the condition will be added to the selection for SET and removed from the selection for CLEAR. The possible conditions with their additional arguements are: @ BOX, lo, hi -- points within the volume. NPEQ, npol -- points belonging to exactly npol polygons. NPLT, npol -- points belonging to less than npol polygons. NPGT, npol -- points belonging to more than npol polygons. SEL_POLYGON(action, [condition ...]) -- Modify polygon selection. Like SEL_POINT, with the following conditions: @ BOX, lo, hi -- polygons with all vertices within the volume. NVEQ, nvert -- polygons with exactly nvert vertices. NVLT, nvert -- polygons with less than nvert vertices. NVGT, nvert -- polygons with greater than nvert vertices. SURFACE, surface -- polygons having the given surface. TYPE, type -- polygons of the given type. NONPLANAR, [limit] -- polygons less planar than the given limit. If limit is omitted, it is the user's default limit. User Interface: ok = NOTIFY(type, line1, [line2, [...]]) -- Puts up a simple notification requester and returns user choice if one given. Type is 1 for simple OK only notification and the function always returns 1. Type 2 is OK/Cancel request and function returns 1 for OK, 0 for Cancel. Type 3 is Yes/No request and the function returns 1 for Yes. The remaining arguments are text lines, which will be in the default color unless preceded by '@' or '!' for increasingly strong emphasis colors. fnam = GETFILENAME(title, dir, [nam]) -- Get a filename from the user. Title is the title text for the file requester. Dir is the start directory and nam is the optional name to start with in that directory. The return value is a name plus a path which clients will have to parse themselves if they want parts of the name. The string "(none)" is returned if the user canceled. A client ARexx macro can put up a requester to get input from the user. The interface is a set of functions to set up the request and get the user's responses. REQ_BEGIN(header) -- Start a requester box interaction. The requester box will have the given header string at the top. id = REQ_ADDCONTROL(label, type, [opts, ...]) -- Add a user input control with the given label text and description. The type is a code for the type of control to create, and subsequent arguments are provided depending on type. type code other args ---- ---- ---------- string S cwidth number N units vector V units v-choice CV text1 text2 text3 ... h-choice CH ... boolean B text-line T line1, line2, ... surface R font F Controls must be all added before any attempt to set or get values, or to post. REQ_SETVAL(id, value ...) -- Set the value of the control. Interpretation of value argument(s) depends on control type. Text-line controls have no value. type value args ---- ---------- string text number value, [default] vector value, [default] choice index boolean state surface name font index ok = REQ_POST() -- Posts request box and returns 1 for Ok, 0 for Cancel. value = REQ_GETVAL(id) -- Get the value of the control. Interpretation of the value string depends on the type of the control. Values are as they are in SETVAL, with vectors always returned as a triple. REQ_END() -- Complete requester interaction. Each request must be complete before the next begins. A client ARexx macro can configure the custom ARexx commands available to the interactive user. ok = RXCMD_ADD(name, cmd) -- Add the given command string to the interface with the given descriptive name. Returns true if item could be added. RXCMD_REMOVE(name) -- Remove the command from interface given its descriptive name. A macro can show how it is progressing through the stages of an operation with the progress meter. Metering is a state that can co-exist with any mode or with a requester. METER_BEGIN(count, header, [footer]) -- Initiate progress meter with the given main header and optional footer. The count is the number of times METER_STEP() will be called before operation is done. METER_STEP() -- Step the progress meter one step closer to completion. Will return an error if the initial count is exceeded, or if the user requests an abort. METER_END() -- Deactivate meter. Can be called before process final count is reached.