Scene Object Agents

 

The Object Agent constructor Scene() creates an Object that contains Data Members and Methods dealing with the current scene's properties. Unlike most of the Object Agents that deal with LightWave items, the Scene()constructor does not have any arguments.

scene = Scene(); // Creates a Scene Object
                        // from current scene.

Note: Remember that not all of the common Data Members and Methods apply to Scene Objects.

Data Members

animfilename
This holds the filename of the animation for the scene.

alertlevel
Indicates the state of the Alert Level setting in Layout. Will be one of ALERT_BEGINNER, ALERT_INTERMEDIATE or ALERT_EXPERT.

alphaprefix
The name of the Alpha channel file-saving prefix. 'nil' if none.

autokeycreate
indicates the state of the Alert Key Create setting in Layout. Will be one of AKC_OFF, AKC_MODIFIED or AKC_ALL.

backdroptype
This backdroptype value holds the type of the current backdrop in the scene. It can be either SOLID or GRADIENT.

boxthreshold
An integer value indicating the current bounding-box threshold setting.

compfg
compbg
compfgalpha

compfg, compbg, and compfgalpha provide information about the scene's current compositing state. All contain either an Image Object Agent for the active compositing images (foreground, background, and foreground alpha, respectively), or they will contain 'nil' if no image is active for that position.

currenttime
currenttime holds the time index that is currently selected in the Layout interface.

doublesidedarealights
returns the state of the double sided area lights toggle

dynamicupdate
dynamicupdate provides information about the state of Layout's dynamic update setting. This information is available in the data member, and will be one of the following:

DYNUP_OFF
DYNUP_DELAYED
DYNUP_INTERACTIVE

displayopts[]
displayopts[] provides information regarding display-related settings in Layout. The following items are the specific elements in the array:

displayopts[1]       Boolean 'true' if Motion Paths are displayed.

displayopts[2]       Boolean 'true' if Handles are displayed.

displayopts[3]       Boolean 'true' if IK Chains are displayed.

displayopts[4]       Boolean 'true' if Cages are displayed.

displayopts[5]       Boolean 'true' if Safe Areas are displayed.

displayopts[6]       Boolean 'true' if Field Charts are displayed.

filename
filename holds a character string that represents the filename of this Scene.

fogtype
The fogtype value holds the type of the fog active in the scene. It can be one of NONE, LINEAR, NONLINEAR1, or NONLINEAR2.

fps
fps contains an integer value that represents the frames-persecond setting for the Scene (default is 30).

framestart, renderstart
framestart, renderstart contains an integer value that represents the beginning frame number to render.

framestep, renderstep
framestep, renderstep contains an integer value that represents the frame step value.

frameend
renderend

frameend, renderend contains an integer value that represents the ending frame number to render.

frameheight
frameheight contains an integer value that represents the height of the frames to be rendered.

framewidth
framewidth contains an integer value that represents the width of the frames to be rendered.

generalopts[ ]
generalopts[] provides information regarding general settings in Layout. The following are the specific elements in the array:

generalopts[1]   Boolean 'true' if Hide Tool Bar is enabled.

generalopts[2]   Boolean 'true' if Right Tool Bar is enabled.

generalopts[3]   Boolean 'true' if Parent In Place is enabled.

generalopts[4]   Boolean 'true' if Fractional Frame is enabled

generalopts[5]   Boolean 'true' if Keys In Slider is enabled.

generalopts[6]   Boolean 'true' if Play Exact Rate is enabled.

generalopts[7]   Boolean 'true' if the interface Auto Key button is enabled.

loadinprogress
returns a value indicating whether loading is in progress

limitedregion[ ]
limitedregion[] holds an array of four integers that represent the location of the Scene's limited region area:

[1] == x0

[2] == y0

[3] == x1

[4] == y1

minsamplesperpixel
minsamplesperpixel contains an integer value that represents the minimum number of samples per pixel in the final image based on the current rendering options.

maxsamplesperpixel
maxsamplesperpixel contains an integer value that represents the maximum number of samples per pixel in the final image based on the current rendering options.

name
name holds a character string that represents the name of the Scene.

numthreads
the number of threads that will be spawned during rendering.

pixelaspect
pixelaspect contains a floating-point number that represents the pixel aspect ratio of the Scene (as pixel-width / pixel-height).

previewstart
previewend, and previewstep

previewstart, previewend, and previewstep represent the values used by the LightWave preview system (and entered into the corresponding edit fields on the user interface).

radiositytype
Contains one of the following three values: LWRT_BACKDROP, LWRT_MONTECARLO,LWRT_FINALGATHER.
radiosityindirectbouncecount
Returns an integer of this value.

raysperevaluation1
Returns an integer of this value.

raysperevaluation2
Returns an integer of this value.

radiosityintensity
Returns a float of this value.

radiosityangulartolerance
Returns a float of this value.

radiositymaximumpixelspacing
Returns a float of this value.

radiosityminimumpixelspacing
Returns a float of this value.

radiositymultiplier
Returns a float of this value.

radiosityfilename
Returns a string of the cache filename.

radiosityflags[]
Each entry is a Boolean true/false that corresponds to one of the following radiosity flags:

1> LWRDFLG_SHOW_NODES
2> LWRDFLG_SHOW_CELLS
3> LWRDFLG_SHOW_COLOR_CELLS
4> LWRDFLG_SHOW_SAMPLES
5> LWRDFLG_SHOW_MISSING_PREPROCESS_SAMPLES
6> LWRDFLG_SHOW_MISSING_RENDER_SAMPLES
7> LWRDFLG_SHOW_SECOND_BOUNCE
8> LWRDFLG_SHOW_BEHIND
9> LWRDFLG_USE_BUMPS

causticsintensity
Returns a float of this value.

causticsaccuracy
Returns an integer of this value.

causticssoftness
Returns an integer of this value.

recursiondepth
recursiondepth holds the integer recursion depth used for rendering.

rendertype
rendertype holds a constant (read-only) integer value that identifies the type of rendering that will take place in the Scene (one of WIRERENDER, QUICKRENDER, or REALISTICRENDER).

renderopts[]
renderopts[] holds an array of 30 Boolean values that represent the current options for the Scene:

[1] LWROPT_SHADOWTRACE
[2] LWROPT_REFLECTTRACE
[3] LWROPT_REFRACTTRACE
[4] LWROPT_FIELDS
[5] LWROPT_EVENFIELDS
[6] LWROPT_MOTIONBLUR
[7] LWROPT_DEPTHOFFIELD
[8] LWROPT_LIMITEDREGION
[9] LWROPT_PARTICLEBLUR
[10] LWROPT_ENHANCEDAA
[11] LWROPT_SAVEANIM
[12] LWROPT_SAVERGB
[13] LWROPT_SAVEALPHA
[14] LWROPT_ZBUFFERAA
[15] LWROPT_RTTRANSPARENCIES
[16] LWROPT_RADIOSITY
[17] LWROPT_CAUSTICS
[18] LWROPT_OCCLUSION
[19] LWROPT_RENDERLINES
[20] LWROPT_INTERPOLATED
[21] LWROPT_BLURBACKGROUND
[22] LWROPT_USETRANSPARENCY
[23] LWROPT_VOLUMETRICRADIOSITY
[24] LWROPT_USEAMBIENT
[25] LWROPT_DIRECTIONALRAYS
[26] LWROPT_LIMITDYNAMICRANGE
[27] LWROPT_CACHERADIOSITY
[28] USEGRADIENT
[29] USEBEHINDTEST
[30] CAUSTICSCACHE

totalpoints
totalpoints contains an integer value that represents the total number of Mesh points in the Scene.

rgbprefix
The name of the RGB file-saving prefix. 'nil' if none.

totalpolygons
totalpolygons contains an integer value that represents the total number of Mesh polygons in the Scene.

Methods backdropRay(time,ray)
The backdropRay(time,ray) method returns the color value, as a vector, intersecting the given ray at the given time index. The ray argument is a vector, and must be normalized.

backdropColor(time)
The backdropColor(time) method returns the color values for the zenith, sky, ground, and nadir, each as a vector, at the given time index.

backdropSqueeze(time)
backdropSqueeze(time)returns the squeeze amount for the sky and ground, each as a floating-point value, at the given time index.
firstSelect()
nextSelect()

firstSelect() and nextSelect() are used to cycle through the objects that are selected in the current scene. The methods are used in a fashion identical to other iteration methods, like firstChild() and nextChild() in the Layout Object Agent.
These two methods are dynamic. If the current selection is altered between calls, then these methods may not behave as expected. The getSelect() method returns all currently selected objects, and should be used if selection-altering commands will be used.

fogMinDist(time)
The fogMinDist(time) method returns the distance from the viewer (typically the camera) at which the fog effect is at a minimum.

fogMaxDist(time)
The fogMaxDist(time) method returns the distance at which the fog effect reaches its maximum.

fogMinAmount(time)
fogMinAmount(time) returns the minimum amount of fog (the amount at the minimum distance). Fog amounts range from 0.0 to 1.0.

fogMaxAmount(time)
fogMaxAmount(time) returns the maximum amount of fog (the amount at the maximum distance).

fogColor(time)
The fogColor(time) method returns, as a vector, the color of the fog at the given time index.

getSelect()
The getSelect() method returns, as a list of Object Agents, all currently selected items in a scene. If getSelect()is called without arguments, all selected items—whether Mesh, Bone, Light, or Camera—will be returned. A flag value can be specified to limit the view of selections to a particular genus. Flags can be MESH, BONE, LIGHT, or CAMERA.
This method is intended to simplify the process of determining selected items, although the firstSelect() and nextSelect() methods are still available for special processing needs.

renderCamera(time)
Given a time index, the renderCamera(time) method will return the active camera in the scene, at that time index, as a Camera Object Agent.
schemaPosition()
schemaPosition() retrieves the X and Y position of an object's entry in Layout's schematic view. Given a name or proxy, this method will return two floating-point values representing this position.

Coupled with the SchematicPosition() Command Sequence function, a script can manage the complete arrangement of Layout's schematic viewport.

visibility()
visibility() determines the display state of an object in the scene. Given either the name of an existing object, or that object's proxy, this method will return one of the following indicators:

VIS_VISIBLE
VIS_HIDDEN
VIS_BOUNDINGBOX
VIS_VERTICES
VIS_WIREFRAME
VIS_FFWIREFRAME
VIS_SHADED
VIS_TEXTURED

server()
This method will return the name of an active plug-in applied to the object. The first argument is the plug-in class to be queried. The second is an optional index value for selecting a specific plug-in.

The plug-in class can be a literal string (like "ItemMotionHandler"), or you can use one of the following pre-defined constants:
SERVER_ANIMLOADER_H SERVER_ANIMLOADER_I
SERVER_ANIMSAVER_H SERVER_ANIMSAVER_I
SERVER_CHANNEL_H SERVER_CHANNEL_I
SERVER_CUSTOMOBJ_H SERVER_CUSTOMOBJ_I
SERVER_DISPLACEMENT_H SERVER_DISPLACEMENT_I
SERVER_ENVIRONMENT_H SERVER_ENVIRONMENT_I
SERVER_IMAGEFILTER_H SERVER_IMAGEFILTER_I
SERVER_PIXELFILTER_H SERVER_PIXELFILTER_I
SERVER_FRAMEBUFFER_H SERVER_FRAMEBUFFER_I
SERVER_MASTER_H SERVER_MASTER_I
SERVER_ITEMMOTION_H SERVER_ITEMMOTION_I
SERVER_OBJREPLACEMENT_H SERVER_OBJREPLACEMENT_I
SERVER_SHADER_H SERVER_SHADER_I
SERVER_TEXTURE_H SERVER_TEXTURE_I
SERVER_VOLUMETRIC_H SERVER_VOLUMETRIC_I
SERVER_ANIMUV_H SERVER_ANIMUV_I
SERVER_CAMERA_H SERVER_CAMERA_I
SERVER_NODE_H SERVER_NODE_I

Where _H indicates a Handler-type server (i.e., "ItemMotionHandler") and _I indicates an Interface-type server (i.e., "ItemMotionInterface").

Examples:

This example creates a Scene object and cycles through the selected items using the firstSelect() and nextSelect() methods.

@version 2.2
@warnings
@name SceneObjectAgent
@script generic

//Set Global Variables
frame = 1;
generic
{
	scene = Scene();

	// Display some Data Members.
	info("Filename: ",scene.filename);
	info("Total Points: ",
	scene.totalpoints);
	info("Total Polygons: ",scene.totalpolygons);

	// Display some Methods.
	info("RenderCamera: ",scene.renderCamera(frame));
	info("BackdropColor: ",scene.backdropColor(frame));

	// Use the firstSelect() and nextSelect()
	// methods to cycle through the objects.
	obj = scene.firstSelect();
	while(obj)
	{
		info(obj);
		obj = scene.nextSelect();
	}
}

Layout Commands


AddPartigon();
Allows you to add an object of Partigon type to layout. 

AddToSelection(itemname/itemid);
Adds an item either by name or id to the list of currently selected objects. 

ApplyServer("<class>","<server>");
This allows you to add the specified plugin to the currently selected item.

AutoFrameAdvance();
Toggles this on or off. 

AutoKey();
Toggles the AutoKey function on or off.

BackdropColor(<float><float> <float> );
BackView();
BottomView();
BoundingBoxThreshold("<threshold>");
CenterItem();
CenterMouse();
ChangeTool();
ClearAudio();
ClearScene();
ClearSelected();
Clone("<clones>");
ContentDirectory("<dirname>");
DecreaseGrid();
DirtyMotion();
Flags the scene as having a motion which needs updating.(I think!)
DynamicUpdate("<level>");
EditServer("<class>","<index>");
This allows you to open the options dialogue for the specified plugin class.

EnableDeformations();
EnableIK();
EnableVIPER();
FirstFrame("<frame>");
FirstItem();
FitAll();
FitSelected();
FractionalFrames();
FramesPerSecond("<fps>");
FrameStep("<frames>");
FreePreview();
FrontView(); 

getfirstitem();
getfirstitem selects the first item of a type in layout.
Example:
getfirstitem("Light");
getfirstitem(MESH);

GoToFrame("<frame>");
GridSize("<size>");
IncreaseGrid();
ItemActive("<active>");
ItemColor("<color>");
ItemLock("<locked>");
ItemVisibility("<visibility>");
LastFrame("<frame>");
LastItem();
LastItem();
MakePreview();
MotionBlurDOFPreview();
NetRender();
NextFrame();
NextItem();
NextKey();
NextSibling();
NextViewLayout();
Pause();
PerspectiveView();
PlayAudio();
PlayBackward();
PlayForward();
PlayPreview();
PreviewFirstFrame("<frame>");
PreviewFrameStep("<frames>");
PreviewLastFrame("<frame>");
PreviewOptions();
PreviousFrame();
PreviousItem();
PreviousKey();
PreviousKey();
PreviousSibling();
PreviousViewLayout();
Quit();
LayoutRadiosityFlags();
This command is used to set one or more radiosity flag values. These values are passed to the command, logically or'ing multiple flags to enable them. Any flag values not included in the resulting or'd value are disabled.
The following environment constants for use with the RadiosityFlags() command:

* LWRDFLG_SHOW_NODES
* LWRDFLG_SHOW_CELLS
* LWRDFLG_SHOW_COLOR_CELLS
* LWRDFLG_SHOW_SAMPLES
* LWRDFLG_SHOW_MISSING_PREPROCESS_SAMPLES
* LWRDFLG_SHOW_MISSING_RENDER_SAMPLES
* LWRDFLG_SHOW_SECOND_BOUNCE
* LWRDFLG_SHOW_BEHIND
* LWRDFLG_USE_BUMPS

RayRecursionLimit("<limit>");
RayTraceReflection();
RayTraceRefraction();
RayTraceShadows();
RayTraceTransparency();
Redraw();
RedrawNow();
Refresh();
RefreshNow();
RemoveFromSelection("<ID>");
RemoveServer("<class>","<index>");
This allows you to remove the specified plugin class at the index specified.

Rename("<name>");
RenderFrame();
RenderScene();
RenderSelected();
RenderThreads("<threads>");
RightView();
SchematicPosition("<X>","<Y>");
SchematicView();
SelectByName("<name>");
SelectByPartialName("<name>");LW 9.3.1 and above
SelectChild();
SelectItem("<ID>");
SelectParent();

Compositing commands

SetBackgroundImage(<id>);(LW>=9.3)
Sets the Layout Background image. ID can be a string (the name of the image), an number (the index of the image) or the image Object agent.

SetForegroundImage(<id>);(LW>=9.3)
Sets the Layout Foreground image. ID can be a string (the name of the image), an number (the index of the image) or the image Object agent.

SetForegroundAlphaImage(<id>);(LW>=9.3)
Sets the Layout Foreground Alpha image. ID can be a string (the name of the image), an number (the index of the image) or the image Object agent.

EnableForegroundFaderAlpha(<bool>);(LW>=9.3)
Enables the foreground alpha. Bool can be true or false

SetForegroundDissolve(<val>);(LW>=9.3)
Sets the Layout Foreground dissolve. A numeric value

EnableForegroundKey(<bool>);(LW>=9.3)
Enables the foreground alpha. Bool can be true or false

SetLowClipColor(<vector>);(LW>=9.3)
Sets the value of the low clip color. vector is an RGB value.

SetHighClipColor(<vector>);(LW>=9.3)
Sets the value of the High clip color. vector is an RGB value.

SyncImageToFrame(<value>);(LW>=9.3)
Sets the sync frame. value is an integer value.

ShowCages();
ShowFieldChart();
ShowHandles();
ShowIKChains();
ShowMotionPaths();
ShowSafeAreas();
ShowTargetLines();
SingleView();

StatusMsg();
This command allows a script to display a message in Layout's "tooltip" area on the main interface without requiring any user interaction (e.g., pressing a button to dismiss a dialog box).

In addition, the text message you provide can be prefaced by a meta-character sequence consisting of a floating point value between 0.0 and 1.0, enclosed within curly braces. If this value is present, it will cause the message displayed to have a background progress bar drawn as well.
For example:

"{.25}Loading object..."

This message would be displayed with 25% of the text background in a different color. By repeatedly calling StatusMsg() with an increasing value in this area, your script can animate a progress status bar along with the message.

generic
{
	for(x = 1;x <= 100;x++)
	{
		StatusMsg("{" + x/100.0 +"}This is a test");
		sleep(100);
	}

	StatusMsg("Done!");
}

Synchronize();
TopView();
Undo();
UpdateMotion();
Forces an update of motions in the scene, for use after say reparenting an item.
ViewLayout("<layout>");
VolumetricLighting();
VolumetricLightingOptions();
VolumetricRadiosity();
Volumetrics();
XYView();
XZView();
ZoomIn();
ZoomInX2();
ZoomOut();
ZoomOutX2();
ZYView();