6. Texture2D and Texture3D Classes

public MyTexture() public MyTexture(DataInputStream in, Scene theScene) throws IOException, InvalidObjectException Every Texture must provide two constructors. The first one has no arguments, and initializes all parameters to their default values. This is used when creating new Texture objects. The second constructor is used when restoring saved Textures, as described in chapter 4. Note that this method is declared to throw an InvalidObjectException. This should be thrown if the information read from the DataInputStream does not match what it expects. For example, a common practice is to begin the saved representation with a version number. That way, if you should later modify your Texture plugin to add more adjustable parameters, you will always be able to identify what version a particular saved Texture corresponds to, and read it in appropriately. If the version number is a value that your plugin does not know how to deal with (perhaps because the file was created with a later version of the plugin), it would throw an InvalidObjectException.

public void writeToFile(DataOutputStream out, Scene theScene) throws IOException This method is the counterpart to the second constructor discussed above. It saves the parameter values to the DataOutputStream. Be sure to save the Texture's name as well as any other parameters you define. You can get it with the getName() method, and set it with the setName() method.

public static String getTypeName() This method must return a string which describes this Texture class. It can, but does not need to, be the same as the class name. This is the text which will appear in the menu of texture types in the "New Texture" window.

public boolean bumpMapped() This method specifies whether this Texture uses bump mapping. If it returns false, the Texture will not be bump mapped, and the value of bumpGrad returned by getTextureSpec() will be ignored. The default implementation of this method returns false. If you want to use bump mapping, you must override it to return true.

public TextureParameter[] getParameters() This method describes the set of per-vertex texture parameters for this Texture. Users can edit the values for these parameters by selecting the "Texture Parameters..." menu item in the object editor window. The default implementation of this method returns null, indicating that there are no per-vertex parameters for this Texture. The constructor for the TextureParameter class is: public TextureParameter(Object owner, String name, float minVal, float maxVal, float defaultVal) owner is the Texture which this parameter belongs to. You should always set it to this. name is the name of the parameter. minVal and maxVal give the range of allowed values for this parameter, and defaultVal gives the default value.

public void getTextureSpec(TextureSpec spec, double x, double y, double xsize, double ysize, double t, float param[]) public void getTextureSpec(TextureSpec spec, double x, double y, double z, double xsize, double ysize, double zsize, double t, float param[]) This method calculate the surface properties, as described in chapter 2. The first form is for Texture2D, and the second is for Texture3D. The values returned in spec should be averaged over a region of width (xsize, ysize, zsize) which is centered at (x, y, z). t is the time (in seconds), and param contains the values for the per-vertex parameters in the same order they were returned by getParameters(). Note that param may be null. This will happen if the object being textured is not vertex based (for example, a sphere or cylinder). In this case, you should use default values for all parameters. It is also possible that param will contain more elements than the number of parameters returned by getParameters(). In this case, the parameter values will be at the beginning of the array, and the additional elements should be ignored.

public void getTransparency(RGBColor transparent, double x, double y, double xsize, double ysize, double t, float param[]) public void getTransparency(RGBColor transparent, double x, double y, double z, double xsize, double ysize, double zsize, double t, float param[]) This method is identical to getTextureSpec(), except that it calculates only the transparent color. The color it returns must be the same as the transparent color which getTextureSpec() returns for the same point. You might wonder why this method is needed. After all, the same information can be obtained from getTextureSpec(). The answer is that it makes rendering much faster. When the Raytracer determines that a point on an object is visible, it must trace a "shadow ray" to every light source in the scene to find out whether it is blocked. These shadow rays frequently account for the majority of all rays involved in rendering a scene. It must then determine the transparency of every object hit by a shadow ray. It could do this by calling getTextureSpec(), but this is quite wasteful. Having a separate method which calculates only the transparency can significantly reduce the rendering time.

public double getDisplacement(double x, double y, double xsize, double ysize, double t, float param[]) public double getDisplacement(double x, double y, double z, double xsize, double ysize, double zsize, double t, float param[]) This method calculates the displacement height for a point on the surface. The default implementation of this method returns NaN, which signals the renderer not to use displacement mapping. If you want your texture to be displacement mapped, you must override this method.

public abstract void getAverageSpec(TextureSpec spec) This method is similar to getTextureSpec(), but instead of calculating the surface properties at a particular point, it returns the average properties over the entire surface. This method is used for a number of purposes: for deciding what color to draw objects in the interactive scene editor, when exporting scenes to foreign file formats, etc. This need not be an accurate mathematical average, but it should give a reasonable representation of the overall appearance of the texture.

public void edit(Frame fr, Scene sc) This method should display a window in which the user can edit the texture, as described in chapter 4. fr is the Frame which should be used as the parent for Dialogs. sc is the Scene this Texture is part of. It is needed if you want to make use of image maps in your texture.

public Texture duplicate() This method returns a new Texture whose parameter values are identical to this one's.

public boolean usesImage(ImageMap image) This method should return true if your Texture uses the specified image map. This is necessary so that the user cannot delete an ImageMap that your Texture is using from the scene. The default implementation returns false. If your Texture uses ImageMaps (either directly, or indirectly through ImageOrColor and ImageOrValue objects), you should override this method.

That's a lot of methods: 13 in all, although several of them can sometimes be omitted. Fortunately, most of them are quite simple to write. Only edit() and getTextureSpec() will usually require significant amounts of time.

Prev: An Antialiased Texture Next: Useful Classes