UNIT IV - Chapter 4 - 3D API

Mobile Technology‎ > ‎Java ME (J2ME)‎ > ‎Book - Mobile Phone Programming using Java ME (J2ME)‎ > ‎UNIT IV‎ > ‎

UNIT IV - Chapter 4 - 3D API

The founders of J2ME released the Java Specification Request (JSR) 184 on November 19, 2003. This specification defines the ‘Mobile 3D Graphics API’. Its main purpose was to bring the power of 3D graphics and animation to the J2ME enabled devices. This specification defines one new package, namely javax.microedition.m3g. This package is an optional package and is compatible with MIDP 1.0, MIDP 2.0 as well as the CDC.

The good thing about this API is that it has been defined keeping into consideration the processing and memory constraints on the mobile devices. Another thing that has been kept in mind while developing this API is that there is a provision for importing the 3D animations built using 3D modeling tools directly from this API. This features makes it very easy to incorporate 3D animations into the midlets.

This API provides us with both scene-graph structure and an immediate mode interface. It also provides us with an efficient file format for storing 3D content. The file formar provided to us has an extension named .m3g. The aim is that 3D modeling softwares can store the data in this file format. This data can then be used in the application directly. This package contains many useful classes for developing application with 3D animations.

Some of the uses of this API can be:

· Development of 3D games

· 3D realistic maps

· 3D multimedia applications

· 3D screen savers

· 3D animations

· 3D user interface

How you use it depends upon your imagination and the budget constraints imposed on you.

javax.microedition.m3g

public class AnimationController

What is it?

This class extends the class Object3D. It controls the position, speed and weight of an animation sequence.

Constructor

· public AnimationController()

This contructor can be used for creating a new AnimationController object. The default values for this new AnimationController object are:

§ active interval: (0, 0) (always active)

§ blending weight: 1.0

§ reference point: (0, 0)

§ speed: 1.0

Methods

· public int getActiveIntervalEnd()

This method returns the ending time of the active interval.

· public int getActiveIntervalStart()

This method returns the starting time of the active interval.

· public float getPosition(int worldTime)

This method returns animation sequence position in number of time units elapsed since the beginning of this animation, until worldTime.

· public float getSpeed()

This method returns the current playback speed of this AnimationController object.

· public float getWeight()

This method returns the current blending weight.

· public void setActiveInterval(int start, int end)

This method is used to set the world time interval during which this animation controller is active.

· public void setPosition(float sequenceTime, int worldTime)

This method is used to set a new playback position for this animation controller relative to world time.

§ public void setSpeed(float speed, int worldTime)

This method is used to set a new playback speed for this animation.

§ public void setWeight(float weight)

This method is used to set the blending weight for this animation controller. The value for blending weight must be positive or zero.

public class AnimationTrack

What is it?

This class associates a KeyframeSequence with an AnimationController and an animatable property.

What is an animatable property?

Animatable property is a scalar or vector variable that the animation system can directly update. The orientation of a Node is a good example of animatable property.

o Constructors

§ public AnimationTrack(KeyframeSequence sequence, int property)

This constructor creates an AnimationTrack object with the given keyframe sequence targeting the given property.

o Fields

§ public static final int ALPHA

This field specifies the following as an animation target:

· Alpha factor of a Node, or

· The alpha component of the Background color

· The Material diffuse color, or

· VertexBuffer default color

§ public static final int AMBIENT_COLOR

This field specifies the ambient color of a Material as an animation target.

§ public static final int COLOR

This field specifies the following as an animation target:

· Color of a Light

· Background, or

· Fog, or

· Texture blend color in Texture2D, or

· VertexBuffer default color

§ public static final int CROP

This field specifies the cropping parameters of a Sprite3D or Background as an animation target.

§ public static final int DENSITY

This field specifies the fog density in Fog as an animation target.

§ public static final int DIFFUSE_COLOR

This field specifies the diffuse color of a Material as an animation target.

§ public static final int EMISSIVE_COLOR

This field specifies the emissive color of a Material as an animation target.

§ public static final int FAR_DISTANCE

This field specifies the far distance of a Camera or Fog as an animation target.

§ public static final int FIELD_OF_VIEW

This field specifies the field of view of a Camera as an animation target.

§ public static final int INTENSITY

This field specifies the intensity of a Light as an animation target.

§ public static final int MORPH_WEIGHTS

This field specifies the morph target weights of a MorphingMesh as an animation target.

§ public static final int NEAR_DISTANCE

This field specifies the near distance of a Camera or Fog as an animation target.

§ public static final int ORIENTATION

This field specifies the orientation component of the transformation of a Transformable object as an animation target.

§ public static final int PICKABILITY

This field specifies the picking enable flag of a Node as an animation target.

§ public static final int SCALE

This field specifies the scaling component of the transformation of a Transformable object as an animation target.

§ public static final int SHININESS

This field specifies the shininess of a Material as an animation target.

§ public static final int SPECULAR_COLOR

This field specifies the specular color of a Material as an animation target.

§ public static final int SPOT_ANGLE

This field specifies the spot angle of a Light as an animation target.

§ public static final int SPOT_EXPONENT

This field specifies the spot exponent of a Light as an animation target.

§ public static final int TRANSLATION

This field specifies the translation component of the transformation of a Transformable object as an animation target.

§ public static final int VISIBILITY

This field specifies the rendering enable flag of a Node as an animation target.

Methods

§ public AnimationController getController()

This method retrieves the animation controller used for controlling this animation track.

§ public KeyframeSequence getKeyframeSequence()

This method returns the keyframe sequence object which defines the keyframe values for this animation track.

§ public int getTargetProperty()

This method returns the property targeted by this AnimationTrack. The value returned is one of the symbolic constants listed above.

§ public void setController(AnimationController controller)

This method specifies the animation controller to be used for controlling this animation track.

public class Appearance

What is it?

§ This class defines a set of component objects that define the rendering attributes of a Mesh or Sprite3D. The attributes of Appearance are grouped into component objects. Each component object contains the data for a set of properties that are functionally and logically related to each other.

Which classes are the Appearance component classes?

The following classes are the Appearance compoenent classes:

· Material

· PolygonMode

· CompositingMode

· Fog

· Texture2D

o Constructors

public Appearance()

This constructor constructs an Appearance object with default values. The following are the default values of the object which is created:

Rendering layer : 0
Polygon mode : null (use defaults)
Compositing mode : null (use defaults)
All textures : null (all texturing units disabled)
Material : null (lighting disabled)
Fog : null (fogging disabled)

o Methods

§ public CompositingMode getCompositingMode()

This method returns the current CompositingMode for this Appearance.

§ public Fog getFog()

This method returns the current fogging attributes for this Appearance.

§ public int getLayer()

This method gives us the current rendering layer for this Appearance.

§ public Material getMaterial()

This method returns the current Material for this Appearance.

§ public PolygonMode getPolygonMode()

This method returns the current PolygonMode for this Appearance.

§ public Texture2D getTexture(int index)

This method retrieves the current texture image and its attributes for the given texturing unit.

§ public void setCompositingMode(CompositingMode compositingMode)

This method sets the CompositingMode to use for this Appearance.

§ public void setFog(Fog fog)

This method sets the fogging attributes to use for this Appearance.

§ public void setLayer(int layer)

This method sets the rendering layer for this Appearance.

§ public void setMaterial(Material material)

This method sets the Material to use when lighting this Appearance.

§ public void setPolygonMode(PolygonMode polygonMode)

This method sets the PolygonMode to use for this Appearance.

§ public void setTexture(int index, Texture2D texture)

This method sets the texture image and its attributes for the given texturing unit.

public class Background

What is it?

The Background class defines whether the viewport has to be cleared and how should it be cleared. The Background object is used for clearing the portions of the frame buffer that correspond to the current viewport.

o Constructors

public Background()

This constructor constructs a new Background with default values. The default values for Background object that is created are:

§ Color clear enable : true (clear the color buffer)

§ Depth clear enable : true (clear the depth buffer)

§ Background color : 0x00000000 (black, transparent)

§ Background image : null (use the background color only)

§ Background image mode : BORDER, BORDER

§ Crop rectangle : undefined (reset at setImage)

o Fields

public static final int ORDER

This field specifies that the imaginary pixels outside of the source image boundaries in X or Y direction are considered to have the background color.

public static final int REPEAT

This field specifies that the imaginary pixels outside of the source image boundaries in X or Y direction are considered to have the same color as the pixel in the corresponding position in the source image.

o Methods

public int getColor()

This method retrieves the current background color.

public int getCropHeight()

This method gets the current cropping rectangle height within the source image.

public int getCropWidth()

This method returns the width of the cropping rectangle within the source image.

public int getCropX()

This method returns the X offset of the cropping rectangle.

public int getCropY()

This method returns the Y offset of the cropping rectangle.

public Image2D getImage()

This method returns the current background image.

public int getImageModeX()

This method returns the X repeat mode.

public int getImageModeY()

This method returns the Y repeat mode.

public boolean isColorClearEnabled()

This method returns true if color buffer clearing is enabled. Else if it is disabled then false is returned.

public boolean isDepthClearEnabled()

This method returns true if depth buffer clearing is enabled. If it is disabled then false is returned.

public void setColor(int ARGB)

This method sets the background color.

public void setColorClearEnable(boolean enable)

This method enables or disables color buffer clearing.

public void setCrop(int cropX, int cropY, int width, int height)

This method sets a cropping rectangle within the background image.

public void setDepthClearEnable(boolean enable)

This method enables or disables depth buffer clearing.

public void setImage(Image2D image)

This method sets the background image or switches from background image mode to background color mode.

public void setImageMode(int modeX, int modeY)

This method sets the background image repeat mode for the X and Y directions.

public class Camera

What is it?

Camera is a scene graph node that defines the position of the viewer in the scene. It also defined the projection from 3D to 2D. In its local coordinate system, it is always facing towards the negative Z axis, (0 0 -1).

o Constructors

public Camera()

This constructor creates a new Camera node with default values. The default values with which the Camera object is created are as follows:

§ Projection mode : PARALLEL

§ View volume : opposite corners at (-1 -1 -1) and (1 1 1)

o Fields

public static int GENERIC

This field specifies a generic 4x4 projection matrix.

public static int PARALLEL

This field specifies a parallel projection matrix.

public static int PERSPECTIVE

This field specifies a perspective projection matrix.

o Methods

public int getProjection(float[] params)

This method returns the type of projection. The type of projection may be GENERIC, PERSPECTIVE or PARALLEL.

public int getProjection(Transform transform)

This method returns the type of projection. The type of projection may be GENERIC, PERSPECTIVE or PARALLEL.

public void setGeneric(Transform transform)

This method sets the given 4x4 transformation as the current projection matrix.

public void setParallel(float fovy, float aspectRatio,float near, float far)

This method constructs a parallel projection matrix and sets that as the current projection matrix.

public void setPerspective(float fovy, float aspectRatio, float near, float far)

This method constructs a perspective projection matrix and sets that as the current projection matrix.

public class CompositingMode

What is it?

CompositingMode is an Appearance component that encapsulates the per-pixel compositing attributes.

o Constructors

public CompositingMode()

This constructor constructs a CompositingMode object with the following default values:

§ blending mode : REPLACE

§ alpha threshold : 0.0

§ depth offset : 0.0, 0.0

§ depth test : Enabled

§ Depth write : Enabled

§ Color write : Enabled

§ Alpha write : Eabled

o Fields

public static final int ALPHA

This field selects the alpha blend mode.

public static final int ALPHA_ADD

This field selects the additive blend mode.

public static final int MODULATE

This field selects the basic modulating blending mode;

public static final int MODULATE_X2

This field selects the brighter modulating blending mode.

public static final int REPLACE

This field selects the replace mode.

o Methods

public float getAlphaThreshold()

This method returns the current alpha threshold.

public int getBlending()

This method returns the currently active blending mode.

public float getDepthOffsetFactor()

This method returns the current depth offset factor.

public float getDepthOffsetUnits()

This method returns the current depth offset in depth units.

public boolean isAlphaWriteEnabled()

This method returns true if alpha writing is enabled. It will return false in other cases.

public boolean isColorWriteEnabled()

This method returns true if color writing is enabled. It will return false in other cases.

public boolean isDepthTestEnabled()

This method returns true if depth testing is enabled. It will return false in other cases.

public boolean isDepthWriteEnabled()

This method returns true if depth writing is enabled. It will return false in other cases.

public void setAlphaThreshold(float threshold)

This method sets the threshold value for alpha testing. In case the alpha component of a fragment is less than the alpha threshold, the fragment is not rendered.

public void setAlphaWriteEnable(boolean enable)

This method enables or disables writing of fragment alpha values into the color buffer.

public void setBlending(int mode)

This method selects a method of combining the pixel to be rendered with the pixel already in the frame buffer. The very last step of the pixel processing pipeline is blending.

public void setColorWriteEnable(boolean enable)

This method enables or disables writing of fragment color values into the color buffer.

public void setDepthOffset(float factor, float units)

This method defines a value that is added to the screen space Z coordinate of a pixel immediately before depth test and depth write.

public void setDepthTestEnable(boolean enable)

This method enables or disables depth testing.

public void setDepthWriteEnable(boolean enable)

This method enables or disables writing of fragment depth values into the depth buffer.

public class Fog

What is it?

Fog is an appearance component that encapsulates the attributes for fogging.

o Constructors

public Fog()

This constructor creates a new Fog object with the following default values:

§ mode : LINEAR

§ density : 1.0 (exponential fog only)

§ near distance : 0.0 (linear fog only)

§ far distance : 1.0 (linear fog only)

§ color: 0x00000000

o Fields

public static final int EXPONENTIAL

This field stands for a parameter to setMode. It specifies exponential fog.

public static final int LINEAR

This field stands for a parameter to setMode. It specifies linear fog.

o Methods

public int getColor()

This method returns the current color of this Fog in 0x00RRGGBB format.

public float getDensity()

This method returns the current density of this Fog.

public float getFarDistance()

This method returns the current distance to the linear fog far plane.

public int getMode()

This method returns the current fog mode which will one of the symbolic constants discussed earlier.

public float getNearDistance()

This method returns the current distance to the linear fog near plane.

public void setColor(int RGB)

This method sets the color of this Fog.

public void setDensity(float density)

This method sets the fog density for exponential fog.

public void setLinear(float near, float far)

This method sets the near and far distances for linear fog.

public void setMode(int mode)

This method sets the fog mode which may either be linear or exponential.

public class Graphics3D

What is it?

Graphics3D is a singleton 3D graphics context that can be bound to a rendering target. All rendering is done through the render methods in this class, including the rendering of World objects. There is no other way to draw anything in this API.

There are four different render methods

· The first method is for rendering an entire World.

· The second method is for rendering scene graph nodes.

· The third and fourth methods are for rendering an individual submesh.

Rendering targets

Before rendering anything or even clearing the screen, the application must bind a rendering target to this Graphics3D, using the bindTarget method. When finished with rendering a frame, the application must release the rendering target by calling the releaseTarget method.

o Fields

· public static final int ANTIALIAS

This field specifies a parameter to the bindTarget method. It specifies that antialiasing should be turned on.

· public static final int DITHER

This field specifies a parameter to the bindTarget method. It specifies that dithering should be turned on.

· public static final int TRUE_COLOR

This field specifies a parameter to the bindTarget method. It specifies that true color rendering should be turned on.

o Methods

· public int addLight(Light light, Transform transform)

This method binds a Light to use in subsequent immediate mode rendering.

· public void bindTarget(Object target)

This method binds the given Graphics or mutable Image2D as the rendering target of this Graphics3D.

· public void bindTarget(Object target, boolean depthBuffer, int hints)

This method binds the given Graphics or mutable Image2D as the rendering target of this Graphics3D. This method is similar to the above discussed variant of bindTarget, but it allows the depth buffering enable flag and the rendering quality hints to be specified.

· public void clear(Background background)

This method clears the viewport as specified in the given Background object.

· public static Graphics3D getInstance()

This method retrieves the single Graphics3D instance that is associated with this application. Thus the same instance will be returned every time this method is called.

· public static Hashtable getProperties()

This method retrieves the implementation specific properties.

· public void releaseTarget()

This method flushes the rendered 3D image to the currently bound target and then releases the target. This ensures that the 3D image is actually made visible on the target that was set in the bindTarget method.

· public void render(Node node, Transform transform)

This method renders the given Sprite3D, Mesh or Group node with the given transformation from local coordinates to world coordinates.

· public void render(VertexBuffer vertices, IndexBuffer triangles, Appearance appearance, Transform transform)

This method renders the given submesh with the given transformation from local coordinates to world coordinates.

· public void render(VertexBuffer vertices, IndexBuffer triangles, Appearance appearance, Transform transform, int scope)

This method renders the given submesh with the given scope and the given transformation from local coordinates to world coordinates.

· public void render(World world)

This method renders an image of world as viewed by the active camera of that World.

· public void resetLights()

This method clears the array of current lights.

· public void setCamera(Camera camera, Transform transform)

This method sets the Camera to use in subsequent immediate mode rendering.

· public void setDepthRange(float near, float far)

This method specifies the mapping of depth values from normalized device coordinates to window coordinates.

· public void setLight(int index, Light light, Transform transform)

This method unbinds or binds a Light for subsequent immediate mode rendering.

· public void setViewport(int x, int y, int width, int height)

This method specifies a rectangular viewport on the currently bound rendering target.

What is a viewport?

The viewport is the area where the view of the current camera will appear.

public class Group

What is it?

The class group defines a scene graph node that stores an unordered set of nodes as its children.

o Constructors

public Group()

This constructor constructs a new Group node and initializes it with an empty list of children.

o Methods

public void addChild(Node child)

This method adds the given node to this Group. It may potentially change the order and indices of the previously added children.

public Node getChild(int index)

This method gets a child by index.

public int getChildCount()

This method returns the number of children directly attached to this group.

public boolean pick(int scope, float x, float y, Camera camera, RayIntersection ri)

This method returns true if the ray intersected a Mesh or a Sprite3D. It will return false in other cases.

public boolean pick(int scope, float ox, float oy, float oz, float dx, float dy, float dz, RayIntersection ri)

This method returns true if the ray intersected a Mesh. It will return false in other cases.

public void removeChild(Node child)

This method removes the given node from this Group. This may potentially change the order and indices of the remaining children.

public class Image2D

What is it?

Image2D is a class that represents two-dimensional image that can be used as a texture, background or sprite image.

What are Mutable and Immutable images in context with Image2D?

o Mutable: The contents of a mutable image can be updated at any time by rendering into it or by using the set method. The changes to this image will be immediately reflected.

o Immutable: The contents of an immutable image are fixed at construction time and can not be changed later.

o Constructors

public Image2D(int format, int width, int height)

This constructor constructs an empty Image2D object with the specified dimensions.

public Image2D(int format, int width, int height, byte[] image)

This constructor constructs an immutable Image2D object by copying pixels from a byte array.

public Image2D(int format, int width, int height, byte[] image, byte[] palette)

This constructor constructs an immutable Image2D object by copying palette indices from a byte array and the palette entries from another byte array.

public Image2D(int format, Object image)

This constructor constructs an immutable Image2D object by copying pixels from a MIDP or AWT image.

o Fields

public static final int ALPHA

This field is a constructor parameter which specifies that this Image2D has an alpha component only.

Note: This kind of an image can not be used as a rendering target or background.

public static final int LUMINANCE

This field is a constructor parameter which specifies that this Image2D has a luminance component only.

Note: This kind of an image can not be used as a rendering target or background.

public static final int LUMINANCE_ALPHA

This field is a constructor parameter which specifies that this Image2D has luminance and alpha components.

Note: This kind of an image can not be used as a rendering target or background.

public static final int RGB

This field is a constructor parameter which specifies that this Image2D has red, green and blue color components.

static int RGBA

This field is a constructor parameter which specifies that this Image2D has red, green, blue and alpha components.

o Methods

public int getFormat()

This method returns the internal format of this Image2D.

public int getHeight()

This method returns the height of this image.

public int getWidth()

This method returns the width of this image.

public boolean isMutable()

This method returns true if this Image2D is mutable. It will return false if it is immutable.

public void set(int x, int y, int width, int height, byte[] image)

This method updates a rectangular area of this Image2D by copying pixels from a byte array. This method can be used only for mutable images.

public abstract class IndexBuffer

What is it?

IndexBuffer extends Object3D class. IndexBuffer class defines how to connect vertices to form a geometric object. Each of its object’s defines a submesh. It is an abstract class that provides no functionality. TriangleStripArray is currently the only derived class of IndexBuffer. TriangleStripArray defines a submesh consisting of triangle strips.

public class KeyframeSequence

What is it?

KeyframeSequence class encapsulates animation data as a sequence of time-stamped vector-valued keyframes. Every keyframe stands for the value of an animated quantity at a specific time instant. The number of vector components per keyframe is specified in the constructor. The number of vector components per keyframe is the same for all keyframes in the sequence.

o Constructors

public KeyframeSequence(int numKeyframes, int numComponents, int interpolation)

This constructor creates a new KeyframeSequence object according to the specified parameters.

o Fields

public static final int CONSTANT

This field tells that this sequence is to be played back just once and not repeated.

public static final int LINEAR

This field is a constructor parameter that specifies that there should be linear interpolation between keyframes.

public static final int LOOP

This field is a parameter to setRepeatMode. It specifies that this sequence is to be repeated indefinitely.

public static final int SLERP

This field is a constructor parameter that specifies spherical linear interpolation of quaternions.

public static final int SPLINE

This field is a constructor parameter that specifies spline interpolation between keyframes.

public static final int SQUAD

This field is a constructor parameter that specifies spline interpolation of quaternions.

public static final int STEP

This field is a constructor parameter that specifies stepping from one keyframe value to the next.

o Methods

public int getDuration()

This method returns the duration of this sequence in sequence time units.

public int getRepeatMode()

This method returns the current repeat mode. Returned values may be CONSTANT or LOOP.

public void setDuration(int duration)

This method sets the duration of this sequence in sequence time units.

public void setKeyframe(int index, int time, float[] value)

This method sets the time position and value of the specified keyframe.

public void setRepeatMode(int mode)

This method sets the repeat mode of this KeyframeSequence. There are two values which can be set: LOOP and CONSTANT.

public void setValidRange(int first, int last)

This method selects the range of keyframes that are included in the animation.

public class Light

What is it?

The class Light is a scene graph node that represents different kinds of light sources. Light sources are used to determine the color of each object according to its Material attributes.

o Constructors

public Light()

This constructor constructs a new Light with the following default values:

•mode: DIRECTIONAL

•color : 0x00FFFFFF (1.0, 1.0, 1.0)

•intensity : 1.0

•attenuation : (1, 0, 0)

•spot angle : 45 degrees

•spot exponent : 0.0

o Fields

public static final int AMBIENT

This field is a parameter to setMode. It specifies an ambient light source.

public static final int DIRECTIONAL

This field is a parameter to setMode. It specifies a directional light source.

public static final int OMNI

This field is a parameter to setMode. It specifies an omnidirectional light source.

public static final int SPOT

This field is a parameter to setMode. It specifies a spot light source.

o Methods

public int getColor()

This method returns the current color of this Light in 0x00RRGGBB format.

public float getConstantAttenuation()

This method returns the current constant attenuation coefficient.

public float getIntensity()

This method returns the current intensity of this Light.

public float getLinearAttenuation()

This method returns the current linear attenuation coefficient.

public int getMode()

This method returns the current mode of this Light.

public float getQuadraticAttenuation()

This method returns the current quadratic attenuation coefficient.

public float getSpotAngle()

This method returns the current spot angle of this Light object.

public float getSpotExponent()

This method returns the current spot exponent of this Light object.

public void setAttenuation(float constant, float linear,float quadratic)

This method sets the attenuation coefficients for this Light object.

public void setColor(int RGB)

This method sets the color of this Light object.

public void setIntensity(float intensity)

This method sets the intensity of this Light object.

public void setMode(int mode)

This method sets the type of this Light object.

public void setSpotAngle(float angle)

This method sets the spot cone angle for this Light object.

public void setSpotExponent(float exponent)

This method sets the spot exponent for this Light object.

public class Loader

What is it?

The class Loader downloads and deserializes scene graph nodes, node components and entire scene graphs. The most convenient way for an application to create and populate a 3D scene is downloading the ready-made pieces of 3D content from an M3G file. You can also get Image2D object loaded if you give a PNG image file in the parameters of the load method.

What is an M3G file?

The JSR 184 defines a file format for efficiently saving the 3D data. This data can be generated with the help of a PC based 3D modeling tool. This file format, which is known as the M3G format is fully compatible with the JSR 184 and thus helps in accelerating the pace development of 3D content for mobile java applications.

o Methods

public static Object3D[] load(byte[] data, int offset)

This method deserializes Object3D instances from the given byte array. This method will start at the given offset.

public static Object3D[] load(String name)

This method returns an array of newly created Object3D instances.

public class Material

What is it?

Material class defines an Appearance component which encapsulates material attributes for lighting computations.

o Constructors

public Material()

This constructor creates a Material object with the following default values:

§ vertex color tracking : false (disabled)

§ ambient color : 0x00333333 (0.2, 0.2, 0.2, 0.0)

§ diffuse color : 0xFFCCCCCC (0.8, 0.8, 0.8, 1.0)

§ emissive color : 0x00000000 (0.0, 0.0, 0.0, 0.0)

§ specular color : 0x00000000 (0.0, 0.0, 0.0, 0.0)

§ shininess : 0.0

o Fields

public static final int AMBIENT

This field is a parameter to the setColor and getColor methods. It specifies that the ambient color component is to be set or retrieved.

public static final int DIFFUSE

This field is a parameter to the setColor and getColor methods. It specifies that the diffuse color component is to be set or retrieved.

public static final int EMISSIVE

This field is a parameter to the setColor and getColor methods. It specifies that the emissive color component is to be set or retrieved.

public static final int SPECULAR

This field is a parameter to the setColor and getColor methods. It specifies that the specular color component is to be set or retrieved.

o Methods

public int getColor(int target)

This method returns the current color of the target property in 0xAARRGGBB format.

public float getShininess()

This method returns the current specular exponent value of this Material.

public boolean isVertexColorTrackingEnabled()

This method returns true if vertex color tracking is enabled. It will return false if it is disabled.

public void setColor(int target, int ARGB)

This method sets the given value to the specified color component(s) of this Material.

public void setShininess(float shininess)

This method sets the shininess of this Material.

public void setVertexColorTrackingEnable(boolean enable)

This method enables or disables vertex color tracking.

public class Mesh

What is it?

A Mesh is a scene graph node that represents a 3D object defined as a polygonal surface. Mesh class represents a conventional rigid body mesh. Its derived classes MorphingMesh and SkinnedMesh extend it with capabilities to transform vertices independently of each other.

o Constructors

public Mesh(VertexBuffer vertices, IndexBuffer submeshes, Appearance appearances)

This constructor constructs a new Mesh object with the given VertexBuffer and submeshes.

public Mesh(VertexBuffer vertices, IndexBuffer submesh, Appearance appearance)

This constructor constructs a new Mesh consisting of only one submesh.

o Methods

public Appearance getAppearance(int index)

This method returns current Appearance of the submesh at the specified index.

public IndexBuffer getIndexBuffer(int index)

This method returns current IndexBuffer at the specified index.

public int getSubmeshCount()

This method returns the number of submeshes in this Mesh.

public VertexBuffer getVertexBuffer()

This method returns the VertexBuffer of this Mesh.

public void setAppearance(int index, Appearance appearance)

This methpd sets the Appearance for the specified submesh.

public class MorphingMesh

What is it?

MorphingMesh is a scene graph node that represents a vertex morphing polygon mesh. It is equivalent to an ordinary Mesh except that in the case of the MorphingMesh vertices that are rendered are computed as a weighted linear combination of the base VertexBuffer and a number of morph target VertexBuffers.

o Constructors

public MorphingMesh(VertexBuffer base, VertexBuffer [] targets, IndexBuffer [] submeshes,Appearance [] appearance)

This constructor contructs a new MorphingMesh with the given base mesh and morph targets.

public MorphingMesh(VertexBuffer base, VertexBuffer [] targets, IndexBuffer submesh, Appearance appearance)

This constructor contructs a new MorphingMesh with the given base mesh and morph targets.

o Methods

public VertexBuffer getMorphTarget(int index)

This method returns the VertexBuffer object at index.

public int getMorphTargetCount()

This method returns the number of morph targets.

public void getWeights(float[] weights)

This method gets the current morph target weights for this mesh.

public void setWeights(float[] weights)

This method sets the weights for all morph targets in this mesh.

public abstract class Node

What is it?

Node is the abstract base class for all scene graph nodes.

Subclasses of class Node

The following are the subclasses of class Node:

Camera: This subclass defines the projection from 3D to 2D. It also defines the position of the viewer in the scene.

Mesh : This subclass defines a 3D object consisting of triangles and also the associated material properties.

Sprite3D: This subclass defines a screen-aligned 2D image with a position in 3D space.

Light : This subclass defines the position, direction, color and other attributes of a light source.

Group : This subclass serves as a root for scene graph branches.

o Fields

public static final int NONE

This field specifies for the setAlignment method that no alignment should be done for the specified axis.

public static final int ORIGIN

This field specifies the origin of the reference node as an orientation reference for the setAlignment method.

public static final int X_AXIS

This field specifies the X axis of the reference node as an orientation reference for the setAlignment method.

public static final int Y_AXIS

This field specifies the Y axis of the reference node as an orientation reference for the setAlignment method.

public static final int Z_AXIS

This field specifies the Z axis of the reference node as an orientation reference for the setAlignment method.

o Methods

public final void align(Node reference)

This method applies alignments to this Node and its descendants.

public float getAlphaFactor()

This method retrieves the alpha factor of this Node.

public Node getParent()

This method returns reference to the parent node. It returns null if there is no parent.

public int getScope()

This method returns the current scope of this Node.

public boolean getTransformTo(Node target, Transform transform)

This method gets the composite transformation from this node to the given node.

public boolean isPickingEnabled()

This method returns the picking enable flag of this Node.

public boolean isRenderingEnabled()

This method returns the rendering enable flag of this Node.

public void setAlignment(Node zRef, int zTarget, Node yRef, int yTarget)

This method sets this node to align with the given other node(s). It may also be used for disabling alignment.

public void setAlphaFactor(float alphaFactor)

This method sets the alpha factor for this Node. This method can be used to fade groups of meshes in and out.

public void setPickingEnable(boolean enable)

This method sets the picking enable flag of this Node.

public void setRenderingEnable(boolean enable)

This method sets the rendering enable flag of this Node.

public void setScope(int scope)

This method sets the scope of this node.

public abstract class Object3D

What is it?

Object3D is an abstract base class for all objects that can be part of a 3D world.

o Methods

public void addAnimationTrack(AnimationTrack animationTrack)

This method adds the given AnimationTrack to this Object3D.

public int animate(int time)

This method updates all animated properties in this Object3D and all Object3Ds that are reachable from this Object3D.

public Object3D duplicate()

This method creates a duplicate of this Object3D without affecting the existing object.

public Object3D find(int userID)

This method returns the first object encountered that has the given user ID. It may return null if no matching objects were found.

public AnimationTrack getAnimationTrack(int index)

This method returns the AnimationTrack at the given index.

public int getAnimationTrackCount()

This method returns the number of AnimationTracks bound to this Object3D.

public int getReferences(Object3D references)

This method returns the number of direct Object3D references in this object.

public int getUserID()

This method returns the current user ID.

public Object getUserObject()

This method returns the current user object associated with this Object3D.

public void removeAnimationTrack(AnimationTrack animationTrack)

This method removes the given AnimationTrack from this Object3D.

public void setUserID(int userID)

This method sets the user ID for this object.

public void setUserObject(Object userObject)

This method associates an arbitary application specific Object with this Object3D. The given user object replaces any previously set object.

public class PolygonMode

What is it?

PolygonMode is an Appearance component encapsulating polygon-level attributes.

o Constructors

public PolygonMode()

This constructor constructs a PolygonMode object with the following default values:

§ culling : CULL_BACK

§ winding : WINDING_CCW

§ shading : SHADE_SMOOTH

§ two-sided lighting: false (disabled)

§ local camera lighting : false (disabled)

§ perspective correction : false (disabled)

o Fields

public static final int CULL_BACK

This field is a parameter to setCulling. It specifies that the back-facing side of a polygon is not to be drawn.

public static final int CULL_FRONT

This field is a parameter to setCulling. It specifies that the front-facing side of a polygon is not to be drawn.

public static final int CULL_NONE

This field is a parameter to setCulling. It specifies that both faces of a polygon are to be drawn.

public static final int SHADE_FLAT

This field is a parameter to setShading. It specifies that flat shading is to be used.

public static final int SHADE_SMOOTH

This field is a parameter to setShading. It specifies that smooth shading is to be used.

public static final int WINDING_CCW

This field is a parameter to setWinding. It specifies that a polygon having its vertices in counter-clockwise order in screen space is to be considered front-facing.

public static final int WINDING_CW

This field is a parameter to setWinding. It specifies that a polygon having its vertices in clockwise order in screen space is to be considered front-facing.

o Methods

public int getCulling()

This method returns the current culling mode.

public int getShading()

This method returns the current shading mode which may either be flat or smooth.

public int getWinding()

This method returns the current winding mode.

public boolean isTwoSidedLightingEnabled()

This method returns true if two-sided lighting is enabled. If it is not enabled it returns false.

public void setCulling(int mode)

This method sets the polygon culling mode. The culling mode defines which sides of a polygon should not be rendered.

public void setLocalCameraLightingEnable(boolean enable)

This method enables or disables local camera lighting.

public void setPerspectiveCorrectionEnable(boolean enable)

This method enables or disables perspective correction.

public void setShading(int mode)

This method sets the polygon shading mode.

public void setTwoSidedLightingEnable(boolean enable)

This method enables or disables two-sided lighting. In case two-sided lighting is enabled the lit colors for the front and back faces of a polygon are computed differently.

public void setWinding(int mode)

This method sets the polygon winding mode to clockwise or counter-clockwise. The winding mode decides which side of the polygon is to be considered front.

public class RayIntersection

What is it?

RayIntersection contains a reference to the intersected Mesh or Sprite3D and information about the intersection point. It is filled in by the pick methods in Group. It is strictly a run-time object. RayIntersection cannot be loaded from a file by Loader class.

o Constructors

public RayIntersection()

This constructor constructs a new RayIntersection object with the following default values:

§ ray origin : (0 0 0)

§ ray direction : (0 0 1)

§ intersected node : null

§ intersected submesh index : 0

§ distance to intersection point : 0.0

§ all texture coordinates : 0.0

§ normal vector: (0 0 1)

o Methods

public float getDistance()

This method returns normalized distance from the pick ray origin to the intersection point.

public Node getIntersected()

This method returns the picked Mesh or Sprite3D object.

public float getNormalX()

This method returns the X component of the surface normal at the intersection point.

public float getNormalY()

This method returns the Y component of the surface normal at the intersection point.

public float getNormalZ()

This method returns the Z component of the surface normal at the intersection point.

public void getRay(float[] ray)

This method retrieves the origin (ox oy oz) and direction (dx dy dz) of the pick ray in that order.

public int getSubmeshIndex()

This method returns index of the intersected submesh. This value is always 0 for sprites.

public float getTextureS(int index)

This method returns the S texcoord of the specified texturing unit at the intersection point.

public float getTextureT(int index)

This method returns the T texcoord of the specified texturing unit at the intersection point.

public class SkinnedMesh

What is it?

SkinnedMesh is a scene graph node that represents a skeletally animated polygon mesh.

o Constructors

public SkinnedMesh(VertexBuffer vertices, IndexBuffer [] submeshes, Appearance [] appearances, Group skeleton)

This constructor constructs a new SkinnedMesh object with the given vertices, submeshes and skeleton.

public SkinnedMesh(VertexBuffer vertices, IndexBuffer submesh, Appearance appearance, Group skeleton)

This constructor constructs a new SkinnedMesh object with the given vertices, submeshes and skeleton.

o Methods

public void addTransform(Node bone, int weight, int firstVertex, int numVertices)

This method associates a weighted transformation (bone) with a range of vertices in this SkinnedMesh.

public Group getSkeleton()

This method returns the skeleton Group of this SkinnedMesh.

public class Sprite3D

What is it?

Sprite3D is a scene graph node that represents a 2-dimensional image with a 3D position.

o Constructors

public Sprite3D(boolean scaled, Image2D image, Appearance appearance)

This constructor constructs a new Sprite3D with the scaling mode, image and appearance defined in the parameters.

o Methods

public Appearance getAppearance()

This method returns the current Appearance of this sprite.

public int getCropHeight()

This method returns the height of the cropping rectangle.

public int getCropWidth()

This method returns the width of the cropping rectangle.

public int getCropX()

This method returns the X offset of the cropping rectangle.

public int getCropY()

This method returns the Y offset of the cropping rectangle.

public Image2D getImage()

This method returns the Image2D object used to draw this sprite.

public boolean isScaled()

This method returns true if this sprite is scaled. If the sprite is unscaled it will return false.

public void setAppearance(Appearance appearance)

This method sets the Appearance of this Sprite3D.

public void setCrop(int cropX, int cropY, int width, int height)

This method sets a cropping rectangle within the source image.

public void setImage(Image2D image)

This method sets the sprite image to display.

public class Texture2D

What is it?

Texture2D is an Appearance component whoch encapsulates a two-dimensional texture image and a set of attributes specifying how the image is to be applied on submeshes.

o Constructors

public Texture2D(Image2D image)

This constructor constructs a new texture object with the given image and setting the texture attributes to their default values as follows:

§ wrapping S : WRAP_REPEAT

§ wrapping T : WRAP_REPEAT

§ level filter : FILTER_BASE_LEVEL

§ image filter : FILTER_NEAREST

§ blending mode : FUNC_MODULATE

§ blend color : 0x00000000 (transparent black)

o Fields

public static final int FILTER_BASE_LEVEL

This field refers to a level filtering parameter to setFiltering method that selects the base level image even if mipmap levels exist.

public static final int FILTER_LINEAR

This field refers to a parameter to setFiltering method that selects linear filtering.

public static final int FILTER_NEAREST

This field refers to a parameter to setFiltering method that selects nearest neighbor filtering.

public static final int FUNC_ADD

This field refers to a parameter to setBlending method which specifies that the texel color is to be added to the fragment color.

public static final int FUNC_BLEND

This field refers to a parameter to setBlending method which specifies that the texture blend color is to be blended into the fragment color in proportion to the texel RGB values.

public static final int FUNC_DECAL

This field refers to a parameter to setBlending method. It specifies that the texel color is to be blended into the fragment color in proportion to the texel alpha.

public static final int FUNC_MODULATE

This field refers to a parameter to setBlending method. It specifies that the texel color and/or alpha are to be multiplied with the fragment color and alpha.

public static final int FUNC_REPLACE

This field refers to a parameter to setBlending method. It specifies that the texel color and/or alpha are to replace the fragment color and alpha.

public static final int WRAP_CLAMP

This field refers to a parameter to setWrapping method. It specifies that the texture image is to be repeated only once.

public static final int WRAP_REPEAT

This field refers to a parameter to setWrapping method. It specifies that the texture image is to be repeated indefinitely.

o Methods

public int getBlendColor()

This method returns the current texture blend color in 0x00RRGGBB format.

public int getBlending()

This method returns the current texture blending function.

public Image2D getImage()

This method returns the current base level texture image.

public int getWrappingS()

This method returns the current S coordinate wrapping mode.

public int getWrappingT()

This method returns the current T coordinate wrapping mode.

public void setBlendColor(int RGB)

This method sets the texture blend color for this Texture2D.

public void setBlending(int func)

This method chooses the texture blend mode or blend function for this Texture2D.

public void setFiltering(int levelFilter, int imageFilter)

This method chooses the filtering mode for this Texture2D.

public void setImage(Image2D image)

This method sets the given Image2D as the texture image of this Texture2D.

public void setWrapping(int wrapS, int wrapT)

This method sets the wrapping mode for the S and T texture coordinates.

public class Transform

What is it?

Transform is a generic 4x4 floating point matrix, representing a transformation.

o Constructors

public Transform()

This constructor constructs a new Transform object and initializes it to the 4x4 identity matrix.

public Transform(Transform transform)

This constructor constructs a new Transform object and initializes it by copying the contents of the transform object given as the parameter.

o Methods

public void get(float[] matrix)

This method retrieves the contents of this transformation as a 16-element float array.

public void invert()

This method inverts this matrix incase it is possible. The existing contents are replaced with the result.

public void postMultiply(Transform transform)

This method multiplies this transformation from the right by the given transformation.

public void postRotate(float angle, float ax, float ay, float az)

This method multiplies this transformation from the right by the given rotation matrix which has been specified in axis-angle form.

public void postRotateQuat(float qx, float qy, float qz, float qw)

This method multiplies this transformation from the right by the given rotation matrix which has been specified in quaternion form.

public void postScale(float sx, float sy, float sz)

This method multiplies this transformation from the right by the given scale matrix. The existing contents are replaced with the result.

public void postTranslate(float tx, float ty, float tz)

This method multiplies this transformation from the right by the given translation matrix. The existing contents are replaced with the result.

public void set(float[] matrix)

This method sets this transformation by copying from the given 16-element float array.

public void set(Transform transform)

This method sets this transformation by copying the contents of the given Transform.

public void setIdentity()

This method replaces this transformation with the 4x4 identity matrix.

public void transform(float[] vectors)

This method multiplies the given array of 4D vectors with this matrix.

public void transform(VertexArray in, float[] out, boolean W)

This method multiplies the elements of the given VertexArray with this matrix. It then stores the transformed values in a float array.

public void transpose()

This method transposes this matrix. The existing contents are replaced with the result.

public abstract class Transformable

What is it?

Transformable is an abstract base class for Node and Texture2D. It defines common methods for manipulating node and texture transformations.

o Methods

public void getCompositeTransform(Transform transform)

This method gets the composite transformation matrix of this Transformable.

public void getOrientation(float[] angleAxis)

This method gets the orientation component of this Transformable.

public void getScale(float[] xyz)

This method gets the scale component of this Transformable.

public void getTransform(Transform transform)

This method gets the matrix component of this Transformable.

public void getTranslation(float[] xyz)

This method gets the translation component of this Transformable.

public void postRotate(float angle, float ax, float ay, float az)

This method multiplies the current orientation component from the right by the given orientation.

public void preRotate(float angle, float ax, float ay, float az)

This method multiplies the current orientation component from the left by the given orientation.

public void scale(float sx, float sy, float sz)

This method multiplies the current scale component by the given scale factors.

public void setOrientation(float angle, float ax, float ay, float az)

This method sets the orientation component of this Transformable.

public void setScale(float sx, float sy, float sz)

This method sets the scale component of this Transformable.

public void setTransform(Transform transform)

This method sets the matrix component of this Transformable by copying in the given Transform.

public void setTranslation(float tx, float ty, float tz)

This method sets the translation component of this Transformable.

public void translate(float tx, float ty, float tz)

This method adds the given offset to the current translation component.

public class TriangleStripArray

What is it?

TriangleStripArray class defines an array of triangle strips. The first three vertex indices define the first triangle. Every subsequent index together with the two previous indices defines a new triangle in it.

o Constructors

public TriangleStripArray(int[] indices, int[] stripLengths)

This constructor constructs a triangle strip array with explicit indices. The parameters take an array of indices along with the lengths of the individual strips.

public TriangleStripArray(int firstIndex, int[] stripLengths)

This constructor constructs a triangle strip array with implicit indices. The parameters define the first index of the first strip along with the lengths of the individual strips.

public class VertexArray

What is it?

VertexArray is an array of integer vectors representing the following:

· Vertex positions

· Normals

· Colors

· Texture coordinates.

o Constructors

public VertexArray(int numVertices, int numComponents, int componentSize)

This constructs constructs a VertexArray based on the value of the parameters.

o Methods

public void set(int firstVertex, int numVertices, byte[] values)

This method copies an array of 8-bit vertex attributes.

public void set(int firstVertex, int numVertices, short[] values)

This method copies an array of 16-bit vertex attributes.

public class VertexBuffer

What is it?

This class holds references to VertexArrays that contain the following for a set of vertices:

o positions

o colors

o normals

o texture coordinates

o Constructor

public VertexBuffer()

This constructor constructs an empty VertexBuffer in which all vertex attributes are set to null.

o Methods

public VertexArray getColors()

This method returns the current VertexArray for vertex colors. It may also return null.

public int getDefaultColor()

This method returns the default vertex color in 0xAARRGGBB format.

public VertexArray getNormals()

This method returns the current VertexArray for vertex normals. It may also return null.

public VertexArray getPositions(float[] scaleBias)

This method returns the current VertexArray for vertex positions. It may also return null.

public VertexArray getTexCoords(int index, float[] scaleBias)

This method returns VertexArray with the texture coordinates for the given texturing unit. It may also return null.

public int getVertexCount()

This method returns the number of vertices currently in this VertexBuffer. This method may also return zero if no vertex arrays are set.

public void setColors(VertexArray colors)

This method sets the per-vertex colors for this VertexBuffer.

public void setDefaultColor(int ARGB)

This method sets the color to use in absence of per-vertex colors.

public void setNormals(VertexArray normals)

This method sets the normal vectors for this VertexBuffer.

public void setPositions(VertexArray positions, float scale, float[] bias)

This method sets the vertex positions for this VertexBuffer.

public void setTexCoords(int index, VertexArray texCoords, float scale, float[] bias)

This method sets the texture coordinates for the specified texturing unit. They are specified with a 2- or 3- component VertexArray.

public class World

What is it?

Class World extends the class Group. It is a special Group node that is a top-level container for scene graphs.

o Constructor

public World()

This constructor creates an empty World. The World so constructed has the following default values:

o Background : null (clear to black)

o Active camera : null (the world is not renderable)

o Methods

public Camera getActiveCamera()

This method returns the camera that is currently used to render this World.

public Background getBackground()

This method returns the current attributes for clearing the frame buffer.

public void setActiveCamera(Camera camera)

This method sets the Camera to use when rendering this World. The camera must also be a descendant of this World at the time of rendering.

public void setBackground(Background background)

This method sets the Background object for this World.

Comments

Library	Search this site