These pages are auto-generated from self-documenting comments embedded in class files.
For more information on breve and steve, refer to the breve homepage.

## Abstract : Control

This class is included as part of the file Control.tz.
To use this class in a simulation, include the line "@use Control."

### Class description:

> Summary: a parent class for the "controller" object required for all simulations.

> The Control object sets up and controls simulations. Every simulation must have one Control subclass. The user subclass of Control should set up the simulation in the "init" method.

> The Control class also acts as the main interaction between the user and the breve environment itself. It provides access to elements of the user interface, for example, so that the user can add menus and other interface features from inside simulations.

> Because the breve engine is designed to run on a variety of systems, there are varying levels of support for some of these features. In some cases, the features won't be supported at all on a system. A background daemon written to use the breve engine, for example, will not place a dialog on the screen and wait for user input.

### Class methods:

> Accepting network uploads

> - accept-upload

> Saving snapshots of simulations

> - save-depth-snapshot
> - save-snapshot

> Updating neighbors

> - update-neighbors

> Getting simulation time

> - get-real-time
> - get-time

> Pausing and stopping simulations

> - end-simulation
> - pause
> - sleep
> - unpause

> Setting and getting the iteration and integration time steps

> - get-integration-step
> - get-iteration-step
> - set-integration-step
> - set-iteration-step

> Setting the Random Seed

> - set-random-seed
> - set-random-seed-from-dev-random

> Creating a New Instance From a Classname String

> - make-new-instance

> Getting Command-Line Arguments

> - get-argument
> - get-argument-count

> Selecting Objects

> - click
> - get-selection

> Background Appearance Options

> - set-background-color
> - set-background-scroll-rate
> - set-background-texture-image
> - set-mountain-skybox
> - set-skybox-images

> Camera & Lighting Options

> - bullet-pan-camera-offset
> - get-camera-offset
> - get-camera-target
> - get-main-camera
> - move-light
> - pan-camera-offset
> - pan-camera-target
> - pivot-camera
> - point-camera
> - set-camera-offset
> - set-camera-rotation
> - set-camera-target
> - watch
> - zoom-camera

> Rendering Options

> - disable-draw-every-frame
> - enable-draw-every-frame
> - set-z-clip

> Special Effects & Drawing Options

> - clear-screen
> - disable-blur
> - disable-fog
> - disable-lighting
> - disable-outline
> - disable-reflections
> - disable-shadow-volumes
> - disable-shadows
> - disable-smooth-drawing
> - disable-text
> - enable-blur
> - enable-fog
> - enable-lighting
> - enable-outline
> - enable-reflections
> - enable-shadow-volumes
> - enable-shadows
> - enable-smooth-drawing
> - enable-text
> - set-blur-factor
> - set-display-text
> - set-display-text-scale
> - set-fog-color
> - set-fog-intensity
> - set-fog-limits
> - toggle-blur
> - toggle-fog
> - toggle-lighting
> - toggle-reflections
> - toggle-shadows
> - toggle-smooth

> Interacting with the User Interface

> - add-menu
> - add-menu-separator
> - beep
> - execute
> - get-mouse-x-coordinate
> - get-mouse-y-coordinate
> - set-interface-item
> - set-light-ambient-color
> - set-light-color
> - set-light-diffuse-color
> - set-light-specular-color
> - show-dialog

> Manipulating and Using Colors

> - get-hsv-color
> - get-rgb-color
> - unique-color

> Archiving & Dearchiving

> - dearchive-xml
> - save-as-xml

> Detecting Light Exposure

> - disable-light-exposure-detection
> - disable-light-exposure-drawing
> - enable-light-exposure-detection
> - enable-light-exposure-drawing
> - get-light-exposure-camera
> - set-light-exposure-source

> Debugging & Performance

> - disable-freed-instance-protection
> - enable-freed-instance-protection
> - get-interface-version
> - report-object-allocation
> - set-output-filter
> - stacktrace

`accept-upload of uploadedObject (object) from host (string)`

> This method is automatically called when an object is uploaded through a NetworkServer. This implementation simply prints out a message saying that the object has been received, but your controller may override the method to take other actions.

`add-menu named menuName (string) for-method theMethod (string)`

> Adds a menu named menuName to the application which will result in a call to theMethod for the calling instance.

> If the calling instance is the Controller object, then the menu will become the "main" simulation menu. Otherwise, the menu will become a contextual menu associated with the specific object in the simulation.

> Note that unlike the handle-collision which sets the collision handler for the whole type (class, that is), this method affects only the instance for which it is called, meaning that each instance of a certain class may have a different menu.

`add-menu-separator`

> Adds a separator menu item--really just an empty menu item.

`beep`

> Plays the system beep sound, if supported by the implementation.

`bullet-pan-camera-offset by amount (vector) steps stepCount (int)`

> Sets the camera in motion to smoothly change the camera offset over stepCount iteration steps, with the physical simulation frozen in the meantime.

`clear-screen`

> Clears the camera to the current background color. This method clears blurred artifacts which are drawn after enabling enable-blur. If blurring has not been enabled, this method has no visual effect.

`click on theObject (object)`

> Called automatically when the user clicks on an theObject from the graphical display window of the simulation. The default behavior of this method is to select the object that was clicked and execute its "click" method, if it exists.

> If you do not wish to allow users to select objects in your simulation, you should implement your own click method in your controller object.

> If you wish to implement your own click method, but still want to maintain the default behavior of this method, make sure you call "super click on theObject" from your method.

> theObject may be NULL--an uninitialized object. This means that a click occurred, but no object was selected, i.e., a deselection event. You should test theObject before calling any of its methods.

`dearchive-xml file filename (string)`

> Asks the controller to dearchive an object from an XML file. The XML file must have been created using archive-as-xml (Object).

`disable-blur`

> Disables blurring. See enable-blur for more information.

`disable-draw-every-frame`

> Allows the rendering engine to drop frames if the simulation is moving faster than the display. This can lead to faster simulations with choppier displays. Not all breve development environments support this option. The Mac OS X application does, as do all threaded command-line breve programs.

> There is rarely any benefit from using this method, except in instances where the drawing of a scene is complex, and the computation is simple. The included DLA.tz demo is an example of one such simulation which benefits immensely from this feature.

`disable-fog`

> Disables fog for the main camera. See enable-fog for more information.

`disable-freed-instance-protection`

> Disabling freed instance protection means that the breve engine will not attempt to keep track of freed objects, and will yield better memory performance when large numbers of objects are being created and destroyed.

> The downside is that improper access of freed instances may cause crashes or unexpected behavior when freed instance protection is disabled. Simulations should thus always use freed instance protection during development and testing, and the feature should only be disabled when the developer is confident that no freed instance bugs exist.

> Freed instance protection may be reenabled with enable-freed-instance-protection, but only instances freed while instance protection is enabled will be protected.

`disable-light-exposure-detection`

> Disables light exposure detection. See enable-light-exposure-detection.

`disable-light-exposure-drawing`

> Disables drawing of the light exposure buffer to the screen.

`disable-lighting`

> disable lighting for the main camera

`disable-outline`

> Disables outline drawing.

`disable-reflections`

> Disable reflections for the main camera. See METHOD(enable-reflections for more information on reflections.

`disable-shadow-volumes`

> Disable shadow volumes for the main camera. See enable-shadow-volumes for more information on shadows.

`disable-shadows`

> Disable "flat" shadows for the main camera. See enable-shadows for more information on shadows.

`disable-smooth-drawing`

> Disable smooth drawing for the main camera. See enable-smooth-drawing for more information.

`disable-text`

> Disable the timestamp and camera position texts (which appear when changing the camera angle or position). The text is on by default. The text can be re-enabled using enable-text.

`enable-blur`

> Enables blur. Blurring simply draws a frame without totally erasing the previous frame.

`enable-draw-every-frame`

> If the method disable-draw-every-frame has been called previously, this method will resort to the default behavior, namely that the rendering engine will try to render an image for each and every iteration of the breve engine.

`enable-fog`

> Enables fog for the main camera. This adds the visual effect of fog to the world. Fog parameters can be set using methods set-fog-color, set-fog-intensity and set-fog-limits.

> Fog and lightmap effects don't mix.

`enable-freed-instance-protection`

> Freed instance protection means that the breve engine retains instances which have been freed in order to make sure that they are not being incorrectly accessed. This has a small memory cost associated with each freed object.

> Freed instance protection is enabled by default, so you'll only need to call this method if it has been disabled using disable-freed-instance-protection.

`enable-light-exposure-detection`

> Experimental

> Light exposure detection will attempt to tell you how much "sunlight" is reaching each object in your simulation. You can set the location of the light source with set-light-exposure-source. Then, use the method get-light-exposure (in Stationary, Mobile, and Link) in order to find out how much light was detected for individual objects.

> The direction of the sunlight is hardcoded towards the world point (0, 0, 0), and only spreads out to fill an angle of 90 degrees. These limitations may be removed in the future if needed.

`enable-light-exposure-drawing`

> Enables drawing of the light exposure buffer to the screen.

`enable-lighting`

> enable lighting for the main camera

`enable-outline`

> Enables outline drawing. Outline drawing is a wireframe black and white draw style. Reflections and textures are ignored when outlining is enabled. Outlining is useful for producing diagram-like images. It looks cool.

`enable-reflections`

> Enable reflections for the main camera. Reflections are used to draw a mirror image of objects in the world onto a single plane. Because of the complexity of drawing reflections, they can only be drawn onto a single plane of a Stationary object--see the method catch-shadows of Stationary for more information. The reflection-catching object must already be defined in order for this method to take effect.

`enable-shadow-volumes`

> Enables shadows drawn using a "shadow volume" algorithm. This is an alternative to the shadows rendered using enable-shadows.

> Shadow volumes allow all objects in the simulation to shadow one-another, as opposed to having objects only shadow a single plane (as is the case with the enable-shadows algorithm). Shadow volumes are in fact superior in every way but one: shadow volumes will not generate accurate shadows of bitmapped objects the way the original algorithm will. If you want high-quality bitmap shadows in your simulation, use enable-shadows, otherwise, shadow volumes are likely the better choice.

`enable-shadows`

> Enable shadows for the main camera. Shadows use the current position of the light in order to render shadows onto a flat plane in the world. Because of the complexity of drawing shadows, they can only be drawn onto a single plane of a Stationary object--see the method catch-shadows of Stationary for more information. The shadow-catching object must already be defined in order for this method to take effect.

> For an improved shadowing algorithm, see enable-shadow-volumes.

`enable-smooth-drawing`

> Enable smooth drawing for the main camera. Smooth drawing enables a smoother blending of colors, textures and lighting. This feature is especially noticeable when dealing with spheres or large objects.

> It is strongly recommended that smooth drawing be enabled whenever lighting is enabled (see enable-lighting). Otherwise, major artifacts may be visible, especially on larger polygons.

> The disadvantage of smooth drawing is a potential performance hit. The degree of this performance hit depends on the number of polygons in the scene. If speed is an issue, it is often best to disable both lighting and smooth drawing.

`enable-text`

> enables the timestamp and camera position texts (which appear when changing the camera angle or position). This is the default setting. The text can be disabled using disable-text.

`end-simulation`

> Ends the simulation gracefully.

`execute command systemCommand (string)`

> Executes the shell command systemCommand using /bin/sh. Returns the output of command. Supported on UNIX-based implementations only (Mac OS X and Linux included), not supported on Windows.

`get-argument at-index theIndex (int)`

> If this instance of breve was run from the command line, this method returns the argument at index theIndex. The argument is always returned as a string, though this may naturally be converted to other types depending on the context. The arguments (like arrays and lists in steve) are zero based, meaning that the first element has index 0. The first argument (the one at index 0) is always the name of the simulation file. Use this method in conjunction with get-argument-count. Make sure you check the number of arguments available before calling this method--requesting an out-of-bounds argument will cause a fatal error in the simulation.

`get-argument-count`

> If this instance of breve was run from the command line, this method returns the number of arguments passed to the program. The first argument is always the name of the simulation file. Use this method in conjunction with get-argument.

`get-camera-offset`

> Returns the current offset from of the camera from its target. Note that the camera offset can be changed manually by the user, so it may be wise to use this function in conjunction with camera movements to ensure consistency.

`get-camera-target`

> Returns the current target of the camera. Note that the camera target can be changed manually by the user, so it may be wise to use this function in conjunction with camera movements to ensure consistency.

`get-hsv-color for-rgb-color rgbColor (vector)`

> All colors in breve expect colors in the RGB format--a vector where the 3 elements represent red, green and blue intensity on a scale from 0.0 to 1.0.

> This method returns the HSV color vector for a given vector rgbColor in RGB color format.

`get-integration-step`

> Returns the current integration step size.

`get-interface-version`

> Returns a string identifying the program using the breve engine. This string is in the format "name/version".

`get-iteration-step`

> Returns the current iteration step size.

`get-light-exposure-camera`

> Returns a camera that can be used to control the light detection light-source.

`get-main-camera`

> Returns the Camera object corresponding to the main camera. This allows you to directly control camera options.

`get-mouse-x-coordinate`

> Returns the X-coordinate of the mouse relative to the simulation window. The value may be negative if the mouse is to the left of the simulation view. See also get-mouse-y-coordinate.

`get-mouse-y-coordinate`

> Returns the Y-coordinate of the mouse. The value may be negative if the mouse is outside of the simulation view, towards the bottom of the screen. See also get-mouse-x-coordinate.

`get-real-time`

> Returns the number of seconds since January 1st, 1970 with microsecond precision.

`get-rgb-color for-hsv-color hsvColor (vector)`

> All colors in breve expect colors in the RGB format--a vector where the 3 elements represent red, green and blue intensity on a scale from 0.0 to 1.0.

> This method returns the RGB color vector for a given vector hsvColor in HSV color format.

`get-selection`

> Returns the "selected" object--the object which has been clicked on in the simulation.

`get-time`

> Returns the simulation time of the world.

`make-new-instance of-class className (string)`

> Returns a new instance of the class className.

`move-light to theLocation (vector) for-light n = 0 (int)`

> Moves the source light to theLocation. The default position is (0, 0, 0) which is the origin of the world.

`pan-camera-offset by amount (vector) steps stepCount (int)`

> Sets the camera in motion to smoothly change the camera offset over stepCount iteration steps.

`pan-camera-target to newTarget (vector) steps stepCount (int)`

> Sets the camera in motion to smoothly change the camera target over stepCount iteration steps.

`pause`

> Pauses the simulation as though the user had done so through the user interface. This method is not supported on all breve client interfaces.

`pivot-camera x dx = 0.0 (float) y dy = 0.0 (float)`

> Rotates the camera (from it's current position) on the x-axis by dx and on the y-axis by dy.

`point-camera at location (vector) from offset = (0, 0, 0) (vector)`

> Points the camera at the vector location. The optional argument offset specifies the offset of the camera relative to the location target.

`report-object-allocation`

> Prints data about current object allocation to the log.

`save-as-xml file filename (string)`

> Writes the entire state of the world to an XML file, filename. filename should have one of the following extensions: .xml, .brevexml, .tzxml.

> After saving the state of the world as an XML file, you can later start a new run of the same simulation from the saved state. You will still need the original steve code which generated the file in order to restart the simulation.

`save-depth-snapshot to filename (string) linearize lin (int) max-dist dist (float)`

> Takes a PNG snapshot of the simulation's depth buffer and saves it to a file named filename, which should end with ".png".

`save-snapshot to filename (string)`

> Takes a PNG snapshot of the current simulation display and saves it to a file named filename, which should end with ".png".

`set-background-color to newColor (vector)`

> Sets the background color of the rendered world to newColor.

`set-background-scroll-rate x xValue (float) y yValue (float)`

> Sets the rate of the background image scrolling. Purely cosmetic.

`set-background-texture-image to newTextureImage (object)`

> Sets the background color of the rendered world to newTexture. newTexture must be a texture returned by the method load-image. Setting the texture to -1 will turn off background texturing.

`set-blur-factor to factor (float)`

> Sets the blur level to factor. Factor should be a value between 1.0, which corresponds to the highest blur level, and 0.0, which corresponds to the lowest blur level.

> Blur must first be enabled using the method enable-blur. Note % that a blur level of 0.0 is still a minor blur--to disable % blur completely, use the method disable-blur.

`set-camera-offset to offset (vector)`

> Offsets the camera from the target by amount. The target of the camera remains the same.

`set-camera-rotation x rx (float) y ry (float)`

> Sets the camera rotation on the x-axis to rx and the y-axis to ry. This method sets the rotation without regard for the current rotation. If you want to offset the camera rotation from the current position, use the method pivot-camera instead.

`set-camera-target to location (vector)`

> Aims the camera at location. The offset of the camera (the offset from the existing target) stays the same.

`set-display-text to theString (string) at-x xLoc = -.95 (float) at-y yLoc = -.95 (float) number messageNumber = 0 (int) with-color theColor = ( 0, 0, 0 ) (vector)`

> Sets a text string in the simulation display. xLoc and yLoc represent the location of the text. The coordinate system used goes from (-1, -1) to (1, 1) with (-1, -1) at the lower left hand corner, (0, 0) in the center of the window and (1, 1) in the top right hand corner.

> The optional argument messageNumber may be used to specify up to 8 different messages.

`set-display-text-scale to scale (double)`

> Sets the scaling factor for text in the display window. See set-display-text and set-display-message for more information on adding text messages to the display window.

`set-fog-color to newColor (vector)`

> Sets the fog color to newColor. Fog must first be turned on with enable-lighting before fog is displayed.

`set-fog-intensity to newIntensity (float)`

> Sets the fog intensity to newIntensity. Fog must first be turned on with enable-lighting before fog is displayed.

`set-fog-limits with-start fogStart (float) with-end fogEnd (float)`

> The calculation which calculates fog needs to know where the fog starts (the point at which the fog appears) and where the fog ends (the point at which the fog has reached it's highest intensity).

> This method sets the start value to fogStart and the end value to fogEnd. fogStart must be greater than or equal to zero. fogEnd must be greater than fogStart.

> Fog must first be turned on with enable-lighting before fog is displayed.

`set-integration-step to timeStep (float)`

> Sets the integration stepsize to timeStep. The integration stepsize determines how quickly the simulation runs: large values (perhaps as high as 1 second) mean that the simulation runs quickly at the cost of accuracy, while low values mean more accuracy, but slower simulations.

> The control object and its subclasses set the integration timeStep to reasonable values, so this method should only be invoked by expert users with a firm grasp of how they want their simulation to run.

> Additionally, this value is only used as a suggestion--the integrator itself may choose to adjust the integration stepsize according to the accuracy of previous timesteps.

`set-interface-item with-id tag (int) to-string newValue (string)`

> This method will set the interface item tag to newValue. This is for simulations which have an OS X nib file associated with them.

`set-iteration-step to timeStep (float)`

> Sets the iteration stepsize to timeStep. The iteration stepsize is simply the number of simulated seconds run between calling the controller object's "iterate" method. This value may not be smaller than the integration timestep.

> The control object and its subclasses set the iteration stepsize to reasonable values, so this method should only be invoked by expert users with a firm grasp of how they want their simulation to run. Small values slow down the simulation considerably.

> For physical simulations, the iteration stepsize should be considerably larger than the integration stepsize. The iteration stepsize, in this case, can be interpreted as the reaction time of the agents in the world to changes in their environment.

`set-light-ambient-color to newColor (vector) for-light n = 0 (int)`

> Sets the ambient, or background, color of the light to newColor. Only has an effect on the rendering when lighting has been turned on using enable-lighting.

`set-light-color to newColor (vector) for-light n = 0 (int)`

> Sets the color of the light to newColor. Only has an effect on the rendering when lighting has been turned on using enable-lighting.

> This method sets both the ambient and diffuse colors, which can also be set individually with set-light-ambient-color and set-light-diffuse-color.

`set-light-diffuse-color to newColor (vector) for-light n = 0 (int)`

> Sets the diffuse, or foreground, color of the light to newColor. Only has an effect on the rendering when lighting has been turned on using enable-lighting.

> The diffuse color is the color coming directly from the light, as opposed to the "ambient" light that is also generated.

`set-light-exposure-source to source (vector)`

> Changes the light source for calculating exposure. See enable-light-exposure-detection.

`set-light-specular-color to newColor (vector) for-light n = 0 (int)`

> Sets the specular, or "shine", color of the light to newColor. Only has an effect on the rendering when lighting has been turned on using enable-lighting.

`set-mountain-skybox`

> A simple shortcut to setup one of the default skyboxes included with breve, used to quickly add a skybox background to a scene. See set-skybox-images for information on setting custom skyboxes.

`set-output-filter to filterLevel (int)`

> Sets the output filter level. This value determines the level of detail used in printing simulation engine errors and messages. The default value, 0, prints only regular output. An output filter of 50 will print out all normal output as well as some warnings and other information useful mostly to breve developers. Other values may be added in the future to allow for more granularity of error detail.

`set-random-seed to newSeed (int)`

> Sets the random seed to newSeed. Setting the random seed determines the way random numbers are chosen. Two runs which use the same random seed will yield the same exact random numbers. Thus, by setting the random number seed manually, you can make simulations repeatable.

`set-random-seed-from-dev-random`

> Sets the random seed to a value read from /dev/random (if available).

> By default, breve sets the random seed based on the current time. This is generally sufficient for most simulations. However, if you are dealing with a setup in which multiple simulations might be launched simultaneously (such as a cluster setup), then you may have a situation in which the same random seed would be used for multiple runs, and this will make you unhappy. Using this method will restore happiness and harmony to your life.

`set-skybox-images to imageList (list)`

> Sets a skybox background from a list of images. imageList must contains 6 strings specifying image files corresponding to the front, back, left, right, top and bottom skybox images respectively. The skybox will not be drawn unless all images load successfully.

`set-z-clip to theDistance (int)`

> Sets the Z clipping plan to theDistance. The Z clipping plan determines how far the camera can see. A short Z clipping distance means that objects far away will not be drawn.

> The default value is 200.0 and this works well for most simulations, so there is often no need to use this method.

> Using a short Z clipping distance improves drawing quality, avoids unnecessary rendering and can speed up drawing during the simulation. However, it may also cause objects you would like to observe in the simulation to not be drawn because they are too far away.

`show-dialog with-title title (string) with-message message (string) with-yes-button yesString (string) with-no-button noString (string)`

> Shows a dialog box (if supported by the current breve environment) and waits for the user to click on one of the buttons.

> If the "yes button" is clicked on, the method returns 1--if the "no button" is clicked, or if the feature is not supported, 0 is returned.

`sleep for-seconds s (float)`

> Pauses execution for s seconds. s does not have to be a whole number. Sleeping for a fraction of a second at each iteration (inside your controller's iterate method) can effectively slow down a simulation which is too fast to observe.

`stacktrace`

> Prints out a breve stacktrace--all of the methods which have been called to get to this point in the simulation. This method is useful for debugging.

`toggle-blur`

> Toggle motion blur for the main camera. See enable-blur for more information on reflections.

`toggle-fog`

> Toggle fog for the main camera

`toggle-lighting`

> toggle lighting for the main camera

`toggle-reflections`

> Toggle reflections for the main camera. See enable-reflections for more information on reflections.

`toggle-shadows`

> Toggle shadows for the main camera. See enable-shadow-volumes and disable-shadow-volumes for more information on shadows.

`toggle-smooth`

> Toggle smooth drawing for the main camera. See enable-smooth-drawing and disable-smooth-drawing for more information.

`unique-color for-number n (int)`

> Returns a unique color for each different value of n up to 198. These colors are allocated according to an algorithm which attempts to give distinguishable colors, though this is subjective and not always possible.

`unpause`

> Pauses the simulation as though the user had done so through the user interface. This method is not supported on all breve client interfaces.

`update-neighbors`

> The neighborhood for each object in the simulation is the set of other objects within a specified radius--calling this method will update the neighborhood list for each object. This method is only useful in conjunction with methods in Real which set the neighborhood size and then later retrieve the neighbor list.

`watch item theObject (object)`

> Points the camera at the Mobile object theObject. If theObject is passed in as 0, then the camera will stop watching a previously watched object.

`zoom-camera to theDistance (float)`

> Zooms the camera to theDistance away from the current target-- whether the target is a vector or object.

Documentation created Thu Jul 3 18:18:12 2008