Local Info



Complete Texture API Introduction

Having got the basic texturing example to work, now you need to get familiar with the rest of the texturing APIs and what they can do for you. In general, Aviatrix3D presents all of the normal texturing options that you can use at the OpenGL level, by bundling them into a couple of classes. This tutorial will be about walking you through the various classes that can contribute to the texturing look rather than as a complete end to end application demo.

If you would like to see the some code that uses a reasonable number of these options then go to the examples/texture directory and look at TextureTransformDemo.java.


Boundary Modes

Specifying boundary modes is a capability of the Texture classes. The base class Texture defines a number of constants for you to use when making the method calls. You have four options to work with that mirror the OpenGL capabilities: BM_CLAMP, BM_CLAMP_TO_EDGE, BM_CLAMP_TO_BOUNDARY and BM_WRAP. These follow the usual well-defined definitions, so no need to go over everything again here.

To set the boundary mode, you need to find the appropriate method call. Since textures can have varying number of dimensions, you won't find all the methods on the base Texture object. There you will only find a single method for the S axis. That's because all texture types at least use this as the baseline, but not everyone uses the other axis. At this level you have just setBoundaryModeS() that takes an int as the only value - where that is on of the BM_* values from above. By default, all boundary modes are set to CLAMP. As an example, to change the T boundary mode of a 2D texture to WRAP, then use this code:


Texture Functions

Texture functions control how the texture image is applied to the object and the underlying object colour and lighting model. Control over this ability is found in the TextureAttributes class. Depending on what you are trying to achieve, there are a number of options for you to play with. The primary method that you'll be making use of will be setTextureMode() as this defines the basics of how the texture is applied, and is also the gateway to the more complex texture combiner modes. By default, the texture mode is set to REPLACE, so if you would like to change it to, say MODULATE, you would need to use the follow code.
TextureAttributes attr = new TextureAttributes();
Making use of the texture combiner modes and methods are covered in the Multitexturing tutorial, so we won't cover them in detail here.

If your texturing needs to make use of explicit blend colour, such as using the MODE_BLEND texture mode or texture combiner options, then you can set the value using the setBlendColor() method. This takes four float values corresponding to the RGBA components. For example, to set a colour of blue, use the following:

attr.setBlendColor(0, 0, 1, 1);


Texture filtering can be used with the same set of capabilities as that provided by OpenGL. The same restrictions also apply - such as attempting to use mipmap filter modes without providing mip maps will disable texturing. The library is just a thin layer based on the requested modes, the real visual behaviour is defined by the OpenGL specification.

Three filter capabilities are defined - minification, magnification and anisotropic. Each have their own methods. Separate constant sets are defined for each filter as although some options look common, the underlying OpenGL calls use different constants to describe each filter type. It also helps us internally work out quickly whether you've passed us a dodgy value or not.

Each of the filter setting methods are found on the base class Texture. There you will find the methods setMinFilter() setMagFilter() for minification and magnification filter parameters respectively, and setAnisotropicFilterMode() and setAnisotropicFilterDegree() for the anisotropic settings. The anisotropic mode method takes a constant defining the mode. Currently there are only two modes available - effectively on and off. The degree method can then be used to set the value needed for the filtering (by default - zero).

Texture Coordinate Generation

Automatic texture coordinate generation is used in a lot of places, particularly for the various forms of environment mapping. All of the available options are wrapped up into the class TexCoordGeneration. The method options available are very simple - there is only one method! No doubt, this will make it more confusing though.

All settings are performed through the setParameter() method. This is roughly analagous to the OpenGL glTexGen*() allowing complete control over the generated output. There are four arugments to setParameter() - the texture axis (S, T, R or Q), the type of generation mode to use, then a parameter value describing the type of generation for the specified mode, and an optional array of values (typically plane equations for the various eye mapping modes). Working this interface effectively requires some knowledge of how the OpenGL texture coordinate generation modes work. Note that each axis can have a separate and completely different set of generation modes, should you choose to do so. It may sound a little odd, but the flexibility is there if you want normal reflections for the S axis, object linear for the T and no generation at all for the R.

Parameter values are only needed if you are using one of the eye or object linear generation modes. For any other mode, we don't look at it internally, so you'll be safe to pass a null there. For some more detailed look at the use of this class in action, head to the Cubic Environment Mapping tutorial.

Current Limitations and Missing Capabilities

The following capabilities cannot be used or expressed through the various APIs available in Aviatrix3D. We're considering designs for them, but have nothing solid yet.
  • Texture Proxy
  • Compressed Textures
  • Automatically Generated Mipmaps
  • Texture Priorities and pinning