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 : Vision

Class Description:

The class Vision allows you to render images in the breve world. The rendered images do not automatically get drawn to the screen, but instead are rendered to red, green and blue pixel buffers stored internally for each Vision object created. You can the retrieve the pixel buffers or specific pixels using the methods available in this file.

Pixel buffers can be used in two ways: they can either be incorporated into the main drawing view (using add-to-world), in which case drawing is done automatically at every timestep; or they can simply not be drawn to screen, in which case they will need to be updated manually using the method update every time you want to read the image.

If a vision is to be drawn to the screen, its size in the drawing window is equal to the size of the vision itself--this means that it does not scale down when the window is resize as the main view does. To position the vision within the larger display, use the method move. Mouse clicks and selections do not "see" visions which are being drawn to the screen, and visions drawn to the screen cannot be rotated or zoomed through the interface. The only way to modify the camera position or orientation of visions is programmatically.

You can retrieve individual pixels using the methods get-red-pixel, get-green-pixel, and get-blue-pixel. Note that using these methods for a large number of pixels will be very slow due to the inherent overhead of making many individual method calls. If you are concerned about performance, you should get the pixel buffers directly and write a plugin to perform computation on the pixels.

Note that when retrieving pixels, the pixel offsets are zero-based, meaning that the counting starts at 0. This means that for a 40x40 vision, the highest pixel offset you can use is 39. Attempting to access row or column 40 will trigger an error.

Note that graphical rendering is often the major bottleneck of a simulation. Because each Vision object created will lead to an extra image being rendered at each timestep, Vision objects can cause a major slowdown in some simulations. The actual slowdown depending on many things including the complexity of the simulation in general, the speed of the processor and graphics card, etc. Try to keep the size of the Vision areas to a minimum.

I can't express how experimental this class is. Think of the most experimental class you can think of. Okay--more. There you go.

Class methods:


add-to-world

Adds this vision to be drawn in the main drawing window.


get-blue-pixel at-x xIndex (int) at-y yIndex (int)

Returns the blue pixel value (0-255) at (xIndex, yIndex).


get-blue-pointer

Returns the pointer to the start of the blue pixel buffer. Pixel buffers are unpadded, so you should expect to find exactly X x Y bytes of data, where X and Y are the size of the vision field.

This method would only ever be used if you are writing a breve plugin to interpret visual data. This point cannot be used within the steve language, it can only be used if passed off to a plugin for external processing. In other words, this method should only be used if you really know what you're doing.

After the object has been inited (init-with), the pointer is valid for the entire lifetime of the Vision object.


get-green-pixel at-x xIndex (int) at-y yIndex (int)

Returns the green pixel value (0-255) at (xIndex, yIndex).


get-green-pointer

Returns the pointer to the start of the green pixel buffer. Pixel buffers are unpadded, so you should expect to find exactly X x Y bytes of data, where X and Y are the size of the vision field.

This method would only ever be used if you are writing a breve plugin to interpret visual data. This point cannot be used within the steve language, it can only be used if passed off to a plugin for external processing. In other words, this method should only be used if you really know what you're doing.

After the object has been inited (init-with), the pointer is valid for the entire lifetime of the Vision object.


get-red-pixel at-x xIndex (int) at-y yIndex (int)

Returns the red pixel value (0-255) at (xIndex, yIndex).


get-red-pointer

Returns the pointer to the start of the red pixel buffer. Pixel buffers are unpadded, so you should expect to find exactly X x Y bytes of data, where X and Y are the size of the vision field.

This method would only ever be used if you are writing a breve plugin to interpret visual data. This point cannot be used within the steve language, it can only be used if passed off to a plugin for external processing. In other words, this method should only be used if you really know what you're doing.

After the object has been inited (init-with), the pointer is valid for the entire lifetime of the Vision object.


init-with x-size x (int) y-size y (int)

Makes a new Vision with size (x, y).


is-in-world

Returns 1 if the vision is currently registered in the world to be drawn in the main drawing window.


look at target (vector) from position (vector)

Move to position and aim at target.


move to-x xValue (int) to-y yValue (int)

Changes the visions position in the global drawing window.


remove-from-world

Stops this vision from being drawn in the main drawing window.


update

If the Vision is not automatically updated (see add-to-world), then this method will update the vision.


Documentation created Tue May 11 10:28:38 2004