Prev: Materials and MaterialSpecs Next: A Sample Material

9. The Material3D Class

We are now ready for a complete description of the Material3D class. What follows is a list of all methods which you can (or must) provide in your subclasses.

public MyMaterial()
public MyMaterial(DataInputStream in, Scene theScene) throws IOException, InvalidObjectException
Every Material must provide two constructors. The first one has no arguments, and initializes all parameters to their default values. This is used when creating new Material objects. The second constructor is used when restoring saved Materials, exactly as with Textures.
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 Material's name and index of refraction, as well as any other parameters you define. You can get the name with the getName() method, and set it with the setName() method. You can get the index of refraction with indexOfRefraction(), and set it with setIndexOfRefraction().
public static String getTypeName()
This method must return a string which describes this Material 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 material types in the "New Material" window.
public double getStepSize()
Materials are rendered by "stepping through" the material, evaluating its properties at a series of points along the path of a light ray which passes through it. This method returns the recommended spacing between these points. It should be equal to (or slightly smaller than) the size of the smallest features of your material which need to be resolved. The default implementation returns 0.1.

Note that the value you return from this method will be used only as a guideline. The actual step size used when rendering the material may be different from this for a variety of reasons. For example:

  • The renderer may use a larger step size to save time when rendering distant objects.
  • The renderer may randomly jitter the step size to remove aliasing artifacts.
  • The user may specifically instruct the renderer to use a larger or smaller step size than the default value.
public boolean isScattering()
This method specifies whether this Material scatters light which passes through it. If it returns false, then no light will be scattered, and the scattering value returned by getMaterialSpec() will be ignored. The default implementation of this method returns false. If you want your material to scatter light, you must override it to return true.

Be aware that Materials which scatter light are much slower to render than non-scattering Materials.

public boolean castsShadows()
This method specifies whether this Material casts shadows. The default implementation returns false. If you want your material to cast shadows, you must override it to return true.

Be aware that Materials which cast shadows are much slower to render than ones which do not.

public void getMaterialSpec(MaterialSpec spec, double x, double y, double z, double xsize, 
        double ysize, double zsize, double t)
This method calculates the material properties, as described in chapter 8. 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).
public void edit(Frame fr, Scene sc)
This method should display a window in which the user can edit the material. fr is the Frame which should be used as the parent for Dialogs. sc is the Scene this Material is part of.
public Material duplicate()
This method returns a new Material whose parameter values are identical to this one's.
public boolean usesImage(ImageMap image)
This method should return true if your Material uses the specified image map. This is necessary so that the user cannot delete an ImageMap that your Material is using from the scene. The default implementation returns false. If your Material uses ImageMaps (either directly, or indirectly through ImageOrColor and ImageOrValue objects), you should override this method.

As you can see, Materials have somewhat fewer methods to implement than Textures, and most of them are directly analogous to Texture methods.

Prev: Materials and MaterialSpecs Next: A Sample Material