Amiga ISO Collection

home *** CD-ROM | disk | FTP | other *** search

/ Amiga ISO Collection / AmigaUtilCD1.iso / GFX / Raytracing / Raytracer / LightWave.lha / Lightwave / Toaster / Arexx_Examples / ModelerARexx3.5.Doc < prev

Wrap

Text File | 1995-04-26 | 20.4 KB | 644 lines

MODELER AREXX INTERFACE ======================= Updated 6/21/94 Modeler operates as a function host for function calls only. "LWModelerARexx.port" is the function host address. 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> flags -- a string that can contain any of a set of characters, shown as <a;b;c>. If the character is present in the string, the flag it represents is set. Likewise, if the character is not present the flag is clear. example: ease <i;o> 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. Certain selection functions are only valid in USER selection mode. See the section on selection below. FUNCTION SUMMARY Parameter types are shown in <>'s. Trailing arguments which are optional are shown in [], where any number of tailing arguments can be omitted. General: NEW() -- Clear all data. EXIT() -- Return to LightWave layout. There can be no commands after this one. UNDO() -- Restore data from last change. DELETE() -- Delete contents of current layers. 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<string>) -- Load data from LightWave file into current layer. SAVE(filename<string>) -- Store data from current layers into LightWave file. State: SETLAYER(<layers>) SETBLAYER(<layers>) -- Switch active or background layers to show given list. SURFACE(name<string>) -- 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<X|Y|Z>, start<number>, end<number>, [ease<i;o>]) -- Set the flex functions to operate on a fixed range along an axis. Ease flags are 'i' for ease-in and 'o' for ease-out. AUTOFLEX(axis<X|Y|Z>, direction<+|->, [ease<i;o>]) -- Set the flex functions to operate on an automatic range along an axis of the given polarity. DEFORMREGION(radius<vector>, [center<vector>, axis<X|Y|Z>]) -- 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<vector>) SHEAR (offset<vector>) MAGNET(offset<vector>) -- Translate points by the given offset. Shear translates along the flex axis. Magnet translates in the deform region. ROTATE(angle<number>, axis<X|Y|Z>, [center<vector>]) TWIST (angle<number>, axis<X|Y|Z>, [center<vector>]) VORTEX(angle<number>, axis<X|Y|Z>, [center<vector>]) -- 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<vector>, [center<vector>]) TAPER(factor<vector>, [center<vector>]) POLE (factor<vector>, [center<vector>]) -- Scale points by the given factors around the given center. Taper uses the flex axis, and pole uses the deform region. BEND(angle<number>, direction<number>, [center<vector>]) -- Bend points by the given bend angle in the direction around the optional center. This function uses the current flex axis. JITTER(radius<vector>) -- Randomly translate points within a given box. (new) JITTER(radius<vector>, [type<GAUSSIAN|UNIFORM|NORMAL|RADIAL>, center<vector>]) -- Randomly translate points using different displacement functions. UNIFORM is the default, which is the same as the old box jitter. GAUSSIAN distributes the offsets in a bell curve around the start point. NORMAL shifts the points in and out along the local surface normal. RADIAL shifts points in and out along a line through a central point given by center. SMOOTH([iterations<number>, strength<number>]) -- Apply smoothing function to attempt to remove kinks in polygons connecting affected points. QUANTIZE(size<vector>) -- Snap all points to a 3D grid defined by the size vector. MERGEPOINTS([mindist<number>]) -- Merge points lying within a certain minimum distance of each other. If no distance is given, it is computed automatically. Object Creation: MAKEBOX(lowcorner<vector>, highcorner<vector>, [nsegments<vector>]) -- Make a box with the given extent and divisions. MAKEBALL(radius<vector>, nsides<int>, nsegments<int>, [center<vector>]) -- Make a globe-style sphere. MAKETESBALL(radius<vector>, level<int>, [center<vector>]) -- Make a tesselated sphere. MAKEDISC(radius<vector>, top<number>, bottom<number>, axis<X|Y|Z>, nsides<int>, [nsegments<int>, center<vector>]) -- Make a disc. MAKECONE {same as disc} -- Make a cone. Top is the pointy end. Text: index<number> = FONTLOAD(filename<string>) -- Load the given font file into the font list. Returns the font index in the table if loaded sucessfully, zero otherwise. count<number> = FONTCOUNT() -- Get number of fonts loaded. index<number> = FONTINDEX(name<string>) -- Get index for name. name<string> = FONTNAME(index<number>) -- Get name for index. width<number> = MAKETEXT(text<string>, index<number>, [cornertype<SHARP|BUFFERED>, spacing<number>, scale<number>, axis<X|Y|Z>, pos<vector>]) -- Generate text using the given font index. Returns width as computed from the font metrics. Spacing is an additional distance to put between characters (normally 0). Scale is a scale factor (or approximate size in meters). Axis and pos define the position of the first character and the plane in which the text will lie. Query Functions: active<layers> = CURLAYER() -- Returns current active layer numbers. background<layers> = CURBLAYER() -- Returns current background layer numbers. empty<layers> = EMPTYLAYERS() -- Returns numbers of empty layers. name<string> = CURSURFACE() -- Returns current surface name. boxdata = BOUNDINGBOX([test<layers>]) -- 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<X|Y|Z>, nsides<int>, [center<vector>, endangle<number>, startangle<number>]) -- Spin template around axis. EXTRUDE(axis<X|Y|Z>, extent<number>, [nsegments<int>]) -- Sweep template along axis. MIRROR(axis<X|Y|Z>, plane<number>) -- Copy selected data, fliping it through a plane. PATHCLONE(...) PATHEXTRUDE(filename<string>, [step<number>, start<number>, end<number>]) -- Load the motion file and extrude or clone selected data according to path interval settings. RAILCLONE(...) RAILEXTRUDE(segments<number>, [divs<KNOTS|LENGTHS>, flags<o;s>, strength<number>]) -- Clone or extrude selected data using rails in background layers. If segments is zero, they are computed automatically, otherwise it is a fixed division. Flags are 'o' for oriented and 's' for scaled. AXISDRILL(operation<CORE|TUNNEL|SLICE|STENCIL>, axis<X|Y|Z>, [surface<string>]) -- Use background layers as template to operate on foreground layers. Surface is used for STENCIL operation. SOLIDDRILL(operation<CORE|TUNNEL|SLICE|STENCIL>, [surface<string>]) -- Use background object to operate on foreground. BOOLEAN(operation<UNION|SUBTRACT|INTERSECT|ADD>) -- Combine background object with foreground data. BEVEL(inset<number>, shift<number>) -- Perform bevel operation on selected polygons. SHAPEBEVEL(pattern) -- Bevel with a shape defined by a series of insets and shifts. The pattern is a blank-separated list of inset/shift pairs, each relative to the original polygon. The same effect can be achieved using iterative bevels, but the results are not always correct because of self- crossing. SMOOTHSHIFT(offset<number>, [maxangle<number>]) -- Shift selected polygons by given offset. Any angles greater than maxangle will cause the surface to break. FLIP() -- Flip sidedness of faces, direction of curves. TRIPLE() -- Convert all polygons into triangles. REMOVEPOLS() -- Remove polygons leaving points. ALIGNPOLS() -- Flip polygons so all are facing the same direction (as much as is possible). UNIFYPOLS() -- Delete any duplicate polygons. CHANGESURFACE(surface<string>) -- Set the surface of all selected polygons. SUBDIVIDE(mode<FLAT|SMOOTH|METAFORM>, [maxangle<number>]) -- Split all triangles into four smaller triangles. (new) Also splits quads into four smaller quads. Metaform option uses the metaform algorithm. (new) FRACSUBDIVIDE(mode<FLAT|SMOOTH|METAFORM>, fractal<number>, [maxangle<number>]) -- Same as subdivide, but applies a fractal displacement to each new vertex as a function of its position. FREEZECURVES() -- Convert all selected curves directly into polygons. 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<int> = ADD_POINT(position<vector>) -- Points are numbered in creation order starting at 1. The index of the new point is returned. ADD_POLYGON(<point number list>) -- Takes a variable number of point numbers as argument. Polygon is created using current default surface. ADD_QUAD(<point number list>) -- 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(<point number list>, [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<number> = XFRM_BEGIN() -- Start a point transformation. Returns number of points in the current layer. If the number returned is zero, there are no points to process and TRANSFORM mode is not entered. pos<vector> = XFRM_GETPOS(index<number>) -- Get position of indexed point. Index is from 1 to N. XFRM_SETPOS(index<number>, position<vector>) -- 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<COPY|SWEEP>) -- Start replication. This is a copy or sweep, given by the argument. REPL_STEP(offset<vector>, scale<vector>, rotation<vector>, [center<vector>]) -- 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,1,0) must be included in the sequence. 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<GLOBAL|USER>) -- Set the selection mode. END_ALL or script termination will reset this mode to GLOBAL. SEL_POINT(action<SET|CLEAR>, [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: VOLUME, lo<vector>, hi<vector> -- points within the volume. CONNECT -- points connected to already selected ones. Only works with SET. NPEQ, npol<number> -- points belonging to exactly npol polygons. NPLT, npol<number> -- points belonging to less than npol polygons. NPGT, npol<number> -- points belonging to more than npol polygons. SEL_POLYGON(action<SET|CLEAR>, [condition ...]) -- Modify polygon selection. Like SEL_POINT, with the following conditions: VOLEXCL, lo<vector>, hi<vector> -- polygons entirely within the volume. VOLINCL, lo<vector>, hi<vector> -- polygons at least partly within the volume. CONNECT -- polygons connected to already selected ones. Only works with SET. NVEQ, nvert<number> -- polygons with exactly nvert vertices. NVLT, nvert<number> -- polygons with less than nvert vertices. NVGT, nvert<number> -- polygons with greater than nvert vertices. SURFACE, surface<string> -- polygons having the given surface. FACE -- face polygons only. CURVE -- curve polygons only. NONPLANAR, [limit<number>] -- polygons less planar than the given limit. If limit is omitted, it is the user's default limit. (new) SEL_INVERT() -- Invert selection. Selected becomes unselected and visa versa. (new) SEL_HIDE(state<SELECTED|UNSELECTED>) -- Hide all selected or unselected data. Default is SELECTED. (new) SEL_UNHIDE() -- Unhide all hiden data. User Interface: ok<bool> = NOTIFY(type<number>, line1<string>, [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<string> = GETFILENAME(title<string>, dir<string>, [nam<string>]) -- 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 cancels. 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<string>) -- Start a requester box interaction. The requester box will have the given header string at the top. id = REQ_ADDCONTROL(label<string>, type<string>, [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 width (number of characters) number N units (flag for meters(1) or unitless(0)) 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<string> number value<number>, [default<number>] vector value<vector>, [default<number>] choice index<number 1..N> boolean state<bool> surface name<string> font index<number 1..fontcount()> ok<bool> = 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<bool> = RXCMD_ADD(name<string>, cmd<string>) -- Add the given command string to the interface with the given descriptive name. Returns true if item could be added. RXCMD_REMOVE(name<string>) -- Remove the command from interface given its descriptive name. cmd<string> = RXFUN_GET(n<number>) -- Get the command string for function key n (1..10). RXFUN_SET(n<number>, cmd<string>) -- Set the command string for function key n (1..10). Since any change made here will be saved in the config file, scripts that do this should probably restore the old command before exiting. 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<int>, header<string>, [footer<string>]) -- 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.