7. Useful Classes

Basic Mathematical Classes

The Vec2, Vec3, Mat4, and RGBColor classes represent respectively a 2-dimensional vector, a 3-dimensional vector, a 4x4 matrix, and a color. All of these classes work pretty much the way you would expect them to. They include a lot of methods, however, so you should spend a while looking through them to see all the things they can do.

User Interface Classes

• MessageDialog

This class presents a modal Dialog containing one or more lines of text, followed by one or more buttons. Clicking any of the buttons dismisses the Dialog. You can then call getChoice() to find out which button was pressed. This is useful for displaying simple messages to the user, or for presenting multiple-choice questions.

• EntriesDialog

This class presents a modal Dialog containing a line of text followed by one or more TextFields, each with a Label next to it. It also contains "OK" and "Cancel" buttons. Clicking either one dismisses the Dialog. You can call getEntries() to get the text that was entered into the TextFields. This is useful for prompting the user to enter information.

• ComponentsDialog

This is similar to EntriesDialog, but more general. Instead of using TextFields, it allows you to specify a list of Components which will be displayed in the Dialog, again with Labels next to each one and with "OK" and "Cancel" buttons at the bottom. After the Dialog is dismissed, you can call clickedOk() to find out which button was used to dismiss it. This is a very flexible class which can be used for a wide variety of purposes.

• PanelDialog

This is similar to ComponentsDialog, but still more general. It displays a Dialog containing an arbitrary Panel which you pass to it, along with "OK" and "Cancel" buttons.

• ColorChooser

This is a Dialog for editing RGBColor objects. It supports RGB, HSV, and HLS color models.

• MaterialPreviewer

This is an essential Component when creating editors for your Textures and Materials. You pass to it a Texture, a Material, or both. It displays a rendered image of a sphere with your Texture and/or Material assigned to it. The user can rotate the sphere with the mouse to see it from different sides. When the Texture or Material changes, call the render() method to recalculate the image.

• ValueSlider

This is a Component used for selecting numeric values. It consists of a Scrollbar and a TextField, each of which can be used for editing the value. If an invalid entry is typed into the text field (either something which is not a number, or a number which is outside the allowed range), the text turns red to alert the user. This class has addActionListener() and addAdjustmentListener() methods, which you can use if you want to be notified when the user presses Return in the TextField or changes the value.

• ValueField

This is similar to ValueSlider, but contains only a TextField. This is useful when the value does not need to be in a fixed range. You can specify various constraints on the allowed value: that it must be nonnegative, that it must be nonzero, and that it must be an integer value.

Pattern Generating Classes

• ImageMap
This represents an image. It can be of arbitrary size, and have up to four color components (red, green, blue, and alpha). Use getColor() to get the color at a particular point in the image, or getComponent() to get the value of a particular component. Both of these methods have built in support for antialiasing.

You can obtain an ImageMap by creating an ImagesDialog. This displays a Dialog with previews of all the ImageMaps in the scene, and allows the user to load new ones, remove currently loaded ones, and select an ImageMap which is then returned by the getSelection() method. In most cases, however, you will not use ImageMaps directly. Instead, you will use the more convenient ImageOrColor and ImageOrValue classes.

If you do decide to use the ImageMap class directly, be sure to read the appendix, which gives important information about them.

• ImageOrColor

This class represents a color which may (or may not) vary according to an ImageMap. Call getColor() to get the color at a particular point. This class provides its own user interface: the getEditingPanel() method returns a Panel which can be used to edit it. The user specifies a color and, optionally, an image. If they specify an image, getColor() returns the product of the color and the image. Otherwise, it simply returns the color.

• ImageOrValue

This is similar to ImageOrColor, but it represents a floating point value instead of a color. The getValue() method returns a number between 0 and 1 which is the product of a user-specified value and, optionally, a component of an image.

• Noise

This class provides an implementation of Ken Perlin's gradient noise function. This is a function which varies smoothly between -1.0 and 1.0, with all of the variation happening on a length scale of about 1. Typically, you will want to add several octaves of this function together to create a fractal noise function. The value() method returns the value of the function at an arbitrary point in space, and the calcGradient() method calculates the gradient of the function (which is necessary when using noise as a bump map). In addition, calcVector() implements a closely related, vector-valued noise function.

• Cells

This class provides an implementation of Steven Worley's cellular texture basis function. This function scatters "feature points" at random locations throughout 3D space. At any point (x, y, z), it defines the function f1(x, y, z) to be the distance to the nearest feature point. It similarly defines f2(x, y, z) as the distance to the second nearest feature point, f3(x, y, z) as the distance to the third nearest, etc. The calcFunctions() method will calculate an arbitrary number of these functions at a given point in space. It also returns a "unique identifier" for the nearest, second nearest, etc. feature points. This is useful, for example, when you want to make cell-like textures where each cell is a different color.

Prev: The Texture2D and Texture3D Classes Next: Materials and MaterialSpecs