yaarq.sys
Class yrqVisual

java.lang.Object
  |
  +--yaarq.sys.yrqVisual
Direct Known Subclasses:
yrqBasicVisual, yrqEffectVisual, yrqFlareVisual, yrqOverlayVisual, yrqParticleVisual

public class yrqVisual
extends java.lang.Object

This class encapsules a Java3D shape3d and adds some further functionallity while easing the use of the related appearance object. The following common effects can be achieved:

Multitexturing: Each visual can have up to four texturing stages. Passing an according texture for the basic, lightmap, bumpmap and reflectionmap paramters automatically sets all stage attributes necessary.

Lightmaps: Lightmaps are done using the ADDSIGNED texture capability, resulting in lightmaps being able to both add and remove light. A lightmap is a greyscale texture featuring values of 128 for no effect, 0 for maximum shadow and 255 for maximum light.

Bumpmaps: Bumpmapping is done in a separate pass, and only if the graphic card supports it. The algorithm used is Dot3 bump mapping, and the maps used shoud have been loaded using the TEXTURE_BUMPMAP flag as a lot of processing is necessary to create a valid bumpmap. Textures used for bumpmapping should be greyscale textures, with white being the background and darker shades denoting desired bump regions.

Reflection maps: For such maps, texture coordinates are automatically created on the fly. Textures used for reflection maps should seamlessly tile. Only spherical environmental mapping has been implemented.

Translucency: The visual class provides support for transparency. Two modes are available: In additive mode, the SRC_ALPHA/ONE rule is used in Java3Ds transparency attributes, resulting in lighting effects. In blend mode, the SRC_ALPHA/ONE_MINUS_SRC_ALPHA rule is used, resulting in seamless blending of visual and background. Effects include e.g. stencil maps (blending with a basic texture that has been loaded using the TEXTURE_ALPHA_MASK flag) and light effects (adding with a basic texture that has been loaded using the TEXTURE_ALPHA_BLEND flag).

Texture animation: Two methods provide support for setting texture coordinates. Using the method that takes four coordinates makes it possible to create scolling effects by setting the coordinates in a cyclical manner ( (counter % repeat_frequency)/repeat_frequency). Using the clip-based method makes it possible to play animations in a texture: Pass the tiling parameters and a tile index counting from the upper left to display a defined clip of the texture.

Automatic viewport alignment: Many effects, e.g. animated lighting effects for explosions, need visuals aligned to the viewport. The class supports this through a state that activates automated viewport orientation.

Material properties: Most rendering systems do not use basic material colors any longer due to the widespread use of textures. However, material properties like emissivity and specular highlights are necessary for many effects. Consequentially, this class provides direct calls for setting emissive and shinyness, but only indirect capabilities to change material properties.

Visuals are engine scene graph objects. They only appear in a scene after they have been added to the appropriate collection, which attaches them to the scene graph. However, all of an instances properties can be manipulated at any time.

The yaarq engine tries to partially encapsule the complexity of Java3D and to provide simple calls for complex but common effects. Of course, many options are lost when complex objects like geometry and appearance are encapsuled and simplified. However, most properties needed for common effects have been included and functions returning the internal shape, appearance and geometry objects are provided for convenience.

TODO: Add method for setting lightmap position and size, add texture animation with rotation


Field Summary
static int COLOR_AMBIENT
          Coloring option: Set ambient color
static int COLOR_DIFFUSE
          Coloring option: Set diffuse color
static int COLOR_EMISSIVE
          Coloring option: Set emissive color
static int COLOR_SPECULAR
          Coloring option: Set specular color
protected  javax.media.j3d.Group m_parent
           
static int MODE_ADD
          Mode constant for use with the setTransparency method: Additive transparency using Java3Ds SRC_ALPHA/ONE rule
static int MODE_BLEND
          Mode constant for use with the setTransparency method: Blended transparency using Java3Ds SRC_ALPHA/ONE_MINUS_SRC_ALPHA rule
static int MODE_NONE
          Mode constant for use with the setTransparency method: No transparency.
static int TEXTURE_DOT3BUMP
          Texturing option: Set bumpmap texture
static int TEXTURE_LIGHTMAP
          Texturing option: Set lightmap texture
static int TEXTURE_MATERIAL
          Texturing option: Set material texture
static int TEXTURE_REFLECT
          Texturing option: Set reflection texture
 
Constructor Summary
protected yrqVisual(javax.media.j3d.Geometry a_geometry, javax.media.j3d.Texture2D a_texMaterial, javax.media.j3d.Texture2D a_texLightMap, javax.media.j3d.Texture2D a_texBumpMap, javax.media.j3d.Texture2D a_texReflection, boolean a_enableLighting, boolean a_enableOrienting, int a_mode, float a_transparency, float a_shininess, float a_brightness)
          Constructs a new visual using passed parameters.
 
Method Summary
 void attach(javax.media.j3d.Group a_group)
          This method attaches the visual to a parent.
 void detach()
          This method detaches the visual from its current parent.
 javax.media.j3d.Shape3D getBaseShape3D()
          This function retrieves the Shape3D object created by the visual and used in the base rendering pass.
 javax.media.j3d.Shape3D getBumpShape3D()
          This function retrieves the Shape3D object created by the visual and used in the bump rendering pass.
protected  javax.media.j3d.Geometry getGeometry()
          This method returns the geometry of the visual
 javax.media.j3d.Group getParent()
          This function returns the parent transform group this visual is currently attached to or null, if it isnt attached to a group.
protected  javax.media.j3d.Texture2D getTexture(int a_type)
          This function returns one of the textures used in the visual.
protected  int getTransparencyMode()
          Returns the transparency mode of the visual.
protected  float getTransparencyValue()
          Returns the transparency value for this visual.
protected  void setBrightness(float a_brightness)
          This method sets the material of the visual to a greyscale level having defined emissivity.
protected  void setColor(int a_type, javax.vecmath.Color3f a_color)
          This function allows setting a specified color component of the underlying material of the visual.
protected  void setGeometry(javax.media.j3d.Geometry a_geometry)
          This method sets the geometry of the visual and replaces any previous geometry present in the visual.
protected  void setShininess(float a_shininess)
          This method sets the material of the visual to a greyscale level having defined shininess, meaning specular and highlight components.
protected  void setTexture(int a_type, javax.media.j3d.Texture2D a_texture)
          This function sets one of the textures used in the visual.
protected  void setTextureAnimation(double a_left, double a_top, double a_width, double a_height)
          This function sets a continuous texture animation to the base material texture.
protected  void setTextureAnimation(int a_clipIndex, int a_clipCountX, int a_clipCountY)
          This function set a clip-based texture animation to the base material texture.
protected  void setTransparency(float a_alpha, int a_mode)
          Sets the transparency factor for the visual.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

COLOR_AMBIENT

public static final int COLOR_AMBIENT
Coloring option: Set ambient color

See Also:
Constant Field Values

COLOR_DIFFUSE

public static final int COLOR_DIFFUSE
Coloring option: Set diffuse color

See Also:
Constant Field Values

COLOR_EMISSIVE

public static final int COLOR_EMISSIVE
Coloring option: Set emissive color

See Also:
Constant Field Values

COLOR_SPECULAR

public static final int COLOR_SPECULAR
Coloring option: Set specular color

See Also:
Constant Field Values

m_parent

protected javax.media.j3d.Group m_parent

MODE_ADD

public static final int MODE_ADD
Mode constant for use with the setTransparency method: Additive transparency using Java3Ds SRC_ALPHA/ONE rule

See Also:
Constant Field Values

MODE_BLEND

public static final int MODE_BLEND
Mode constant for use with the setTransparency method: Blended transparency using Java3Ds SRC_ALPHA/ONE_MINUS_SRC_ALPHA rule

See Also:
Constant Field Values

MODE_NONE

public static final int MODE_NONE
Mode constant for use with the setTransparency method: No transparency.

See Also:
Constant Field Values

TEXTURE_DOT3BUMP

public static final int TEXTURE_DOT3BUMP
Texturing option: Set bumpmap texture

See Also:
Constant Field Values

TEXTURE_LIGHTMAP

public static final int TEXTURE_LIGHTMAP
Texturing option: Set lightmap texture

See Also:
Constant Field Values

TEXTURE_MATERIAL

public static final int TEXTURE_MATERIAL
Texturing option: Set material texture

See Also:
Constant Field Values

TEXTURE_REFLECT

public static final int TEXTURE_REFLECT
Texturing option: Set reflection texture

See Also:
Constant Field Values
Constructor Detail

yrqVisual

protected yrqVisual(javax.media.j3d.Geometry a_geometry,
                    javax.media.j3d.Texture2D a_texMaterial,
                    javax.media.j3d.Texture2D a_texLightMap,
                    javax.media.j3d.Texture2D a_texBumpMap,
                    javax.media.j3d.Texture2D a_texReflection,
                    boolean a_enableLighting,
                    boolean a_enableOrienting,
                    int a_mode,
                    float a_transparency,
                    float a_shininess,
                    float a_brightness)
Constructs a new visual using passed parameters. All parameters can be changed at runtime. Attach the visual to a component to make it visible in the scene.

Parameters:
a_geometry - The geometry to use in construction of the visual
a_texMaterial - The basic material texture
a_texLightMap - The lightmap texture to multiply with the material texture
a_texBumpMap - The bumpmap to apply
a_texReflection - The reflection map to apply
a_enableLighting - Flag for enabling per-vertex lighting calculation
a_enableOrienting - Flag for enabling auto-orientation
a_transparency - The alpha-transparency of the constructed visual, 0-1f
a_shininess - The specular and highlight of the constructed visual, 0-1f
a_brightness - The emissive component of the constructed visual, 0-1f
Method Detail

attach

public void attach(javax.media.j3d.Group a_group)
This method attaches the visual to a parent.

Parameters:
a_group - The group to which to attach

detach

public void detach()
This method detaches the visual from its current parent.


getBaseShape3D

public javax.media.j3d.Shape3D getBaseShape3D()
This function retrieves the Shape3D object created by the visual and used in the base rendering pass. The function is provided for convenience: Applications wishing to exert more control over the rendering process than this class provides can access the created visual here and modify properties at will.

Returns:
A Java3D-compatible Shape3D object which can be attached to the scenegraph, containing the base-pass shape

getBumpShape3D

public javax.media.j3d.Shape3D getBumpShape3D()
This function retrieves the Shape3D object created by the visual and used in the bump rendering pass. The function is provided for convenience: Applications wishing to exert more control over the rendering process than this class provides can access the created visual here and modify properties at will.

Returns:
A Java3D-compatible Shape3D object which can be attached to the scenegraph, containing the base-pass shape

getGeometry

protected javax.media.j3d.Geometry getGeometry()
This method returns the geometry of the visual

Returns:
The geometry used by the visual

getParent

public javax.media.j3d.Group getParent()
This function returns the parent transform group this visual is currently attached to or null, if it isnt attached to a group.

Returns:
The transformgroup to which the visual is attached.

getTexture

protected javax.media.j3d.Texture2D getTexture(int a_type)
This function returns one of the textures used in the visual. Which texture to return is defined by one of the TEXTURE_XXX constants to be passed for the type parameter.

Parameters:
a_type - The type of the texture to return. One of the TEXTURE_xxx constants
Returns:
The texture

getTransparencyMode

protected int getTransparencyMode()
Returns the transparency mode of the visual. One of the MODE_xxx constants.

Returns:
Global transparency value of the visual

getTransparencyValue

protected float getTransparencyValue()
Returns the transparency value for this visual. Usage of this value is dependend on the transparency mode set for the visual.

Returns:
Global transparency value of the visual

setBrightness

protected void setBrightness(float a_brightness)
This method sets the material of the visual to a greyscale level having defined emissivity. Lighting is disabled. The method is provided for convenience, to allow setting fully textured visuals not needing any material color to a given level of emissive light.

The values set by the convenience methods setBrightness and setShininess are only valid until the next call to setColor. Setting individual color components of the visual overrides previous settings.

Parameters:
a_brightness - The brightness of the visual, 0-1f

setColor

protected void setColor(int a_type,
                        javax.vecmath.Color3f a_color)
This function allows setting a specified color component of the underlying material of the visual. Pass one of the COLOR_xxx constants and a color value to set material color. This overrides settings for emissive and shininess until the next call to that methods.

Parameters:
a_type - Type of color to set. Must be one of the COLOR_xxx constants
a_color - The color to set

setGeometry

protected void setGeometry(javax.media.j3d.Geometry a_geometry)
This method sets the geometry of the visual and replaces any previous geometry present in the visual.


setShininess

protected void setShininess(float a_shininess)
This method sets the material of the visual to a greyscale level having defined shininess, meaning specular and highlight components. Lighting is enabled. The method is provided for convenience, to allow setting fully textured visuals not needing any material color to a given level of emissive light.

The values set by the convenience methods setBrightness and setShininess are only valid until the next call to setColor. Setting individual color components of the visual overrides previous settings.

Parameters:
a_shininess - The shininess of the visual, 0-1f

setTexture

protected void setTexture(int a_type,
                          javax.media.j3d.Texture2D a_texture)
This function sets one of the textures used in the visual. Which texture to set is defined by one of the TEXTURE_XXX constants to be passed for the type parameter. All texturing states are adjusted automatically when this function is called.

Parameters:
a_type - The type of the texture to set. One of the TEXTURE_xxx constants
a_texture - The texture to set

setTextureAnimation

protected void setTextureAnimation(double a_left,
                                   double a_top,
                                   double a_width,
                                   double a_height)
This function sets a continuous texture animation to the base material texture. Use it to set the base material texture to any position in a (0,1) normalized frame of reference.

Parameters:
a_left - Left clip position, normalized (0-1)
a_top - Top clip position, normalized (0-1)
a_width - Width of clip to use, normalized (0-1)
a_height - Height of clip to use, normalized (0-1)

setTextureAnimation

protected void setTextureAnimation(int a_clipIndex,
                                   int a_clipCountX,
                                   int a_clipCountY)
This function set a clip-based texture animation to the base material texture. Use it to set the base material texture to a clip indexed by the index parameter in a rectangular tiling clip starting top/left in the texture, having the provided number of clips in the x (left) and y(top) direction.

Parameters:
a_clipIndex - Index of the clip within the texture
a_clipCountX - Number of clips in X direction
a_clipCountY - Number of clips in Y direction

setTransparency

protected void setTransparency(float a_alpha,
                               int a_mode)
Sets the transparency factor for the visual. Transparency can be additive, blended or disabled, pass one of the MODE_xxx constants as the mode parameter to switch modes.

Parameters:
a_alpha - Global transparency factor for this visual
a_mode - Transparency mode for this visual