Class Direct3dRMFrame
public class Direct3dRMFrame implements IDirect3dRMFrame
{
// Methods
public void addChild(Direct3dRMFrame child);
public void addLight(Direct3dRMLight val);
public void addMoveCallback(IFrameMoveCallback fmC,
IUnknown args);
public void addRotation(int typ, float x, float y, float z, float
theta);
public void addScale(int typ, float sx, float sy, float sz);
public void addTransform(int t, float[] val);
public void addTranslation(int t, float x, float y, float z);
public void addVisual(Direct3dRMVisual v);
public void addVisualFrame(Direct3dRMFrame v);
public void addVisualMesh(Direct3dRMMesh v);
public void addVisualMeshBuilder(Direct3dRMMeshBuilder v);
public void addVisualShadow(Direct3dRMShadow v);
public void addVisualTexture(Direct3dRMTexture v);
public void addVisualUserVisual(Direct3dRMUserVisual v);
public void deleteChild(Direct3dRMFrame c);
public void deleteLight(Direct3dRMLight l);
public void deleteMoveCallback(IFrameMoveCallback fn,
IUnknown args);
public void deleteVisual(Direct3dRMVisual v);
public void deleteVisualFrame(Direct3dRMFrame v);
public void deleteVisualMesh(Direct3dRMMesh v);
public void deleteVisualMeshBuilder(Direct3dRMMeshBuilder v);
public void deleteVisualShadow(Direct3dRMShadow v);
public void deleteVisualTexture(Direct3dRMTexture v);
public void deleteVisualUserVisual(Direct3dRMUserVisual v);
public Direct3dRMFrameArray getChildren();
public int getColor();
public Direct3dRMLightArray getLights();
public int getMaterialMode();
public void getOrientation(Direct3dRMFrame ref, D3dVector dir,
D3dVector up);
public Direct3dRMFrame getParent();
public void getPosition(Direct3dRMFrame ref, D3dVector position);
public void getRotation(Direct3dRMFrame ref, D3dVector axis,
float[] theta);
public Direct3dRMFrame getScene();
public int getSceneBackground();
public DirectDrawSurface getSceneBackgroundDepth();
public int getSceneFogColor();
public int getSceneFogEnable();
public int getSceneFogMode();
public void getSceneFogParams(float[] start, float[] end, float[]
density);
public int getSortMode();
public Direct3dRMTexture getTexture();
public void getTextureTopology(int[] u, int[] v);
public void getTransform(float[] val);
public void getVelocity(Direct3dRMFrame ref, D3dVector vel,
int rotation);
public Direct3dRMVisualArray getVisuals();
public int getZbufferMode();
public void inverseTransform(D3dVector d, D3dVector s);
public void loadFromFileByPos(String filename, int position,
int flags, ILoadTextureCallback c, IUnknown pUser);
public void lookAt(Direct3dRMFrame tgt, Direct3dRMFrame ref,
int val);
public void move(float delta);
public void setColor(int c);
public void setColorRGB(float r, float g, float b);
public void setMaterialMode(int val);
public void setOrientation(Direct3dRMFrame reference, float dx,
float dy, float dz, float ux, float uy, float uz);
public void setPosition(Direct3dRMFrame reference, float x, float
y, float z);
public void setRotation(Direct3dRMFrame reference, float x, float
y, float z, float theta);
public void setSceneBackground(int c);
public void setSceneBackgroundDepth(DirectDrawSurface s);
public void setSceneBackgroundImage(Direct3dRMTexture i);
public void setSceneBackgroundRGB(float r, float g, float b);
public void setSceneFogColor(int c);
public void setSceneFogEnable(int enable);
public void setSceneFogMode(int c);
public void setSceneFogParams(float s, float e, float d);
public void setSortMode(int val);
public void setTexture(Direct3dRMTexture t);
public void setTextureTopology(int wrap_u, int wrap_v);
public void setVelocity(Direct3dRMFrame reference, float x, float
y, float z, int with_rotation);
public void setZbufferMode(int val);
public void transform(D3dVector d, D3dVector s);
}
Applications use the methods of the Direct3dRMFrame class to interact with framesan object's frame of reference.
The Direct3dRMFrame class inherits the following methods from the Direct3dRMObject class:
- addDestroyCallback
- duplicate
- deleteDestroyCallback
- getAppData
- getClassName
- getName
- setAppData
- setName
The Direct3dRMFrame object is obtained by calling the createFrame method.
public void addChild(Direct3dRMFrame child);
Adds a child frame to a frame hierarchy.
Return Value:
No return value.
Parameter | Description |
child
| The Direct3dRMFrame object that will be added as a child.
|
Remarks:
If the frame being added as a child already has a parent, this method removes it from its previous parent before adding it to the new parent.
To preserve an object's transformation, use the getTransform method to retrieve the object's transformation before using the addChild method. Then, reapply the transformation after the frame is added.
public void addLight(Direct3dRMLight val);
Adds a light to a frame.
Return Value:
No return value.
Parameter | Description |
val
| The Direct3dRMLight object to be added to the frame.
|
public void addMoveCallback(IFrameMoveCallback fmC, IUnknown args);
Adds a callback function for special movement processing.
Return Value:
No return value.
Parameter | Description |
fmC
| The callback interface that contains an application-defined callback function.
|
args
| Application-defined data to be passed to the callback function.
|
See Also: move, deleteMoveCallback
public void addRotation(int typ, float x, float y, float z, float theta);
Adds a rotation about (x, y, z) by the number of radians specified in theta.
Return Value:
No return value.
Parameter | Description |
typ
| A value of combine type that specifies how to combine the new rotation with any current frame transformation.
|
x
| The axis about which to rotate.
|
y
| The axis about which to rotate.
|
z
| The axis about which to rotate.
|
theta
| The angle of rotation, in radians.
|
Remarks:
The specified rotation changes the matrix only for the frame identified by this object. This method changes the objects in the frame only once, unlike setRotation, which changes the matrix with every render tick.
public void addScale(int typ, float sx, float sy, float sz);
Scales a frame's local transformation by (sx, sy, sz).
Return Value:
No return value.
Parameter | Description |
typ
| The value of combine type that specifies how to combine the new scale with any current frame transformation.
|
sz
| The scale factor in the x direction.
|
sy
| The scale factor in the y direction.
|
sz
| The scale factor in the z direction.
|
Remarks:
The specified transformation changes the matrix only for the frame identified by this object.
public void addTransform(int t, float[] val);
Transforms the local coordinates of the frame by the given affine transformation according to the value of the t parameter.
Return Value:
No return value.
Parameter | Description |
t
| The value of combine type that specifies how to combine the new transformation with any current transformation.
|
val
| The array variable that defines the transformation matrix to be combined.
|
Remarks:
Although a 4-by-4 matrix is given, the last column must be the transpose of [0 0 0 1] for the transformation to be affine.
The specified transformation changes the matrix only for the frame identified by this Direct3dRMFrame object.
public void addTranslation(int t, float x, float y, float z);
Adds a translation by (x, y, z) to a frame's local coordinate system.
Return Value:
No return value.
Parameter | Description |
t
| The value of combine type that specifies how to combine the new translation with any current translation.
|
x
| The position change in the x direction.
|
y
| The position change in the y direction.
|
z
| The position change in the z direction.
|
Remarks:
The specified translation changes the matrix only for the frame identified by this object.
public void addVisual(Direct3dRMVisual v);
Adds a visual object to a frame.
Return Value:
No return value.
Remarks:
Visual objects include meshes and textures. When a visual object is added to a frame, it becomes visible if the frame is in view. The visual object is referenced by the frame.
public void addVisualFrame(Direct3dRMFrame v);
Adds a visual frame to the frame object.
Return Value:
No return value.
public void addVisualMesh(Direct3dRMMesh v);
Adds a visual mesh to the frame object.
Return Value:
No return value.
public void addVisualMeshBuilder(Direct3dRMMeshBuilder v);
Adds a mesh builder object to the frame object.
Return Value:
No return value.
public void addVisualShadow(Direct3dRMShadow v);
Adds a shadow object to the frame object.
Return Value:
No return value.
Parameter | Description |
v
| The Direct3dRMShadow object to be added.
|
public void addVisualTexture(Direct3dRMTexture v);
Adds a texture object to the frame object.
Return Value:
No return value.
public void addVisualUserVisual(Direct3dRMUserVisual v);
Adds a user visual object to the frame object.
Return Value:
No return value.
public void deleteChild(Direct3dRMFrame c);
Removes a frame from the hierarchy. If the frame is not referenced, it is destroyed along with any child frames, lights, and meshes.
Return Value:
No return value.
public void deleteLight(Direct3dRMLight l);
Removes a light from a frame and destroys it if it is no longer referenced. When a light is removed from a frame, it no longer affects meshes in the scene its frame was in.
Return Value:
No return value.
public void deleteMoveCallback(IFrameMoveCallback fn, IUnknown args);
Removes a callback function that performed special motion processing.
Return Value:
No return value.
Parameter | Description |
fn
| The callback interface that contains an application-defined callback function.
|
args
| Application-defined data that was passed to the callback function.
|
See Also: addMoveCallback, move
public void deleteVisual(Direct3dRMVisual v);
Removes a visual object from a frame and destroys it if it is no longer referenced.
Return Value:
No return value.
public void deleteVisualFrame(Direct3dRMFrame v);
Deletes a visual frame from the frame object.
Return Value:
No return value.
public void deleteVisualMesh(Direct3dRMMesh v);
Deletes a mesh object from the frame object.
Return Value:
No return value.
public void deleteVisualMeshBuilder(Direct3dRMMeshBuilder v);
Deletes a mesh builder object from the frame object.
Return Value:
No return value.
public void deleteVisualShadow(Direct3dRMShadow v);
Deletes a shadow object from the frame object.
Return Value:
No return value.
Parameter | Description |
v
| The Direct3dRMShadow object to be deleted.
|
public void deleteVisualTexture(Direct3dRMTexture v);
Deletes a texture object from the frame object.
Return Value:
No return value.
public void deleteVisualUserVisual(Direct3dRMUserVisual v);
Deletes a user visual object from the frame object.
Return Value:
No return value.
public Direct3dRMFrameArray getChildren();
Retrieves a list of child frames in the form of a Direct3dRMFrameArray object.
Return Value:
Returns the Direct3dRMFrameArray object if successful; otherwise, null.
See Also: com.ms.directX.Direct3dRMFrameArray
public int getColor();
Retrieves the color of the frame.
Return Value:
Returns the color of the Direct3dRMFrame object.
See Also: setColor
public Direct3dRMLightArray getLights();
Retrieves a list of lights in the frame in the form of a Direct3dRMLightArray object.
Return Value:
Returns the Direct3dRMLightArray object if successful; otherwise, null.
See Also: com.ms.directX.Direct3dRMLightArray
public int getMaterialMode();
Retrieves the material mode of the frame.
Return Value:
Returns a value of material mode type that specifies the current material mode.
See Also: setMaterialMode
public void getOrientation(Direct3dRMFrame ref, D3dVector dir,
D3dVector up);
Retrieves the orientation of a frame relative to the given reference frame.
Return Value:
No return value.
Parameter | Description |
ref
| The Direct3dRMFrame object to be used as the reference.
|
dir
| The D3dVector objects that receive the directions of the frame's z-axis.
|
up
| The D3dVector objects that receive the directions of the frame's y-axis.
|
See Also: setOrientation
public Direct3dRMFrame getParent();
Retrieves the parent frame of the current frame.
Return Value:
Returns the Direct3dRMFrame object if successful; null otherwise.
Remarks:
If the current frame is the root, this method returns null.
public void getPosition(Direct3dRMFrame ref, D3dVector position);
Retrieves the position of a frame, relative to the given reference frame. (For example, this method retrieves the distance of the frame from the reference.) The distance is stored in the position parameter as a vector, rather than as a linear measure.
Return Value:
No return value.
Parameter | Description |
ref
| The Direct3dRMFrame object to be used as the reference.
|
position
| The D3dVector object that receives the frame's position.
|
See Also: setPosition
public void getRotation(Direct3dRMFrame ref, D3dVector axis, float[] theta);
Retrieves the rotation of the frame, relative to the given reference frame.
Return Value:
No return value.
Parameter | Description |
ref
| The Direct3dRMFrame object to be used as the reference.
|
axis
| The D3dVector object that receives the frame's axis of rotation.
|
theta
| The array variable that receives the frame's rotation, in radians.
|
See Also: setRotation
public Direct3dRMFrame getScene();
Retrieves the root frame of the hierarchy containing the given frame.
Return Value:
Returns the Direct3dRMFrame object if successful; otherwise, null.
public int getSceneBackground();
Retrieves the background color of a scene.
Return Value:
Returns the color.
public DirectDrawSurface getSceneBackgroundDepth();
Retrieves the current background-depth buffer for the scene.
Return Value:
Returns the DirectDrawSurface object if successful; otherwise, returns null.
See Also: setSceneBackgroundDepth
public int getSceneFogColor();
Retrieves the fog color of a scene.
Return Value:
Returns the fog's color.
public int getSceneFogEnable();
Returns whether fog is currently enabled for this scene.
Return Value:
Returns true if fog is enabled, otherwise, returns false.
public int getSceneFogMode();
Retrieves the current fog mode for this scene.
Return Value:
Returns a value of the fog mode type that specifies the current fog mode.
public void getSceneFogParams(float[] start, float[] end, float[] density);
Retrieves the current fog parameters for this scene.
Return Value:
No return value.
Parameter | Description |
start
| The array variables that receive the fog start values.
|
end
| The array variables that receive the fog end values.
|
density
| The array variables that receive the fog density values.
|
public int getSortMode();
Retrieves the sorting mode used to process child frames.
Return Value:
Returns a value of the D3DRMSORT_ type that specifies the sorting mode.
See Also: setSortMode
public Direct3dRMTexture getTexture();
Retrieves the texture of the given frame.
Return Value:
Returns the Direct3dRMTexture object if successful; otherwise, null.
See Also: setTexture
public void getTextureTopology(int[] u, int[] v);
Retrieves the topological properties of a texture when it is mapped onto objects in the given frame.
Return Value:
No return value.
Parameter | Description |
u
| Array variable that is set to true if the texture is mapped in the u direction.
|
v
| Array variable that is set to true if the texture is mapped in the v direction.
|
See Also: setTextureTopology
public void getTransform(float[] val);
Retrieves the local transformation of the frame as a 4-by-4 affine matrix.
Return Value:
No return value.
Parameter | Description |
val
| The array variable that receives the frame's transformation.
|
public void getVelocity(Direct3dRMFrame ref, D3dVector vel, int rotation);
Retrieves the velocity of the frame, relative to the given reference frame.
Return Value:
No return value.
Parameter | Description |
ref
| The Direct3dRMFrame object to be used as the reference.
|
vel
| A D3dVector object that receives the frame's velocity.
|
rotation
| A flag specifying whether the rotational velocity of the object is taken into account when retrieving the linear velocity. If this parameter is true, the object's rotational velocity is included in the calculation.
|
See Also: setVelocity
public Direct3dRMVisualArray getVisuals();
Retrieves a list of visuals in the frame.
Return Value:
Returns the Direct3dRMVisualArray object if successful; otherwise, null.
public int getZbufferMode();
Determines whether z-buffering is enabled or disabled.
Return Value:
Returns one value of D3DRMZBUFFER_ type.
See Also: setZbufferMode
public void inverseTransform(D3dVector d, D3dVector s);
Transforms the vector in the s parameter in world coordinates to model coordinates, and returns the result in the d parameter.
Return Value:
No return value.
Parameter | Description |
d
| A D3dVector object that receives the result of the transformation.
|
s
| The D3dVector object that is the source of the transformation.
|
See Also: transform
public void loadFromFileByPos(String filename, int position, int flags,
ILoadTextureCallback c, IUnknown pUser);
Loads a Direct3dRMFrame object.
Return Value:
No return value.
Parameter | Description |
filename
| The name of the file containing the object to be loaded.
|
position
| The position of the object to be loaded. This is a value that gives the object's order in the file. This parameter can be null.
|
flags
| The value of the load options type.
|
c
| The callback interface that contains a load texture callback function called to load any textures used by the object that require special formatting. This parameter can be null.
|
pUser
| Application-defined data passed to the load texture callback function.
|
Remarks:
By default, this method loads the first frame hierarchy in the file specified by the filename parameter. The frame that calls this method is used as the parent of the new frame hierarchy.
public void lookAt(Direct3dRMFrame tgt, Direct3dRMFrame ref, int val);
Faces the frame toward the target frame (relative to the given reference frame) and locks the rotation by the given constraints.
Return Value:
No return value.
Parameter | Description |
tgt
| The Direct3dRMFrame objects to be used as the target.
|
ref
| The Direct3dRMFrame objects to be used as the reference.
|
val
| The value of frame constraint type that specifies the axis of rotation constrained.
|
public void move(float delta);
Applies the rotations and velocities for all frames in the given hierarchy.
Return Value:
No return value.
Parameter | Description |
delta
| The amount to change the velocity and rotation by.
|
public void setColor(int c);
Sets the color of the frame. This color is used for meshes in the frame when the material mode is D3DRMMATERIAL_FROMFRAME.
Return Value:
No return value.
Parameter | Description |
c
| New color for the frame.
|
See Also: getColor, setMaterialMode
public void setColorRGB(float r, float g, float b);
Sets the color of the frame. This color is used for meshes in the frame when the material mode is D3DRMMATERIAL_FROMFRAME.
Return Value:
No return value.
Parameter | Description |
r
| The red component of a new color for the frame.
|
g
| The green component of a new color for the frame.
|
b
| The blue component of a new color for the frame.
Each component of the color should be in the range of 0 to 1.
|
See Also: setMaterialMode
public void setMaterialMode(int val);
Sets the material mode for a frame. The material mode determines the source of material information for visuals rendered with the frame.
Return Value:
No return value.
Parameter | Description |
val
| The material mode type.
|
See Also: getMaterialMode
public void setOrientation(Direct3dRMFrame reference, float dx, float dy,
float dz, float ux, float uy, float uz);
Aligns a frame so that its z-direction points along the direction vector [dx, dy, dz] and its y-direction aligns with the vector [ux, uy, uz].
Return Value:
No return value.
Parameter | Description |
reference
| The Direct3dRMFrame object to be used as the reference.
|
dx
| The new z axis for the frame.
|
dy
| The new z axis for the frame.
|
dz
| The new z axis for the frame.
|
ux
| The new y axis for the frame.
|
uy
| The new y axis for the frame.
|
uz
| The new y axis for the frame.
|
Remarks:
The default orientation of a frame has a direction vector of [0, 0, 1] and an up vector of [0, 1, 0].
If [ux, uy, uz] is parallel to [dx, dy, dz], no action is taken; otherwise, the [ux, uy, uz] vector passed is projected onto the plane that is perpendicular to [dx, dy, dz].
See Also: getOrientation
public void setPosition(Direct3dRMFrame reference, float x, float y,
float z);
Sets the position of a frame, relative to the frame of reference. This method places the frame a distance of [x, y, z] from the reference. When a child frame is created within a parent frame, it is placed at [0, 0, 0] in the parent frame.
Return Value:
No return value.
Parameter | Description |
reference
| The Direct3dRMFrame object to be used as the reference.
|
x
| The x coordinate of the new position for the frame.
|
y
| The y coordinate of the new position for the frame.
|
z
| The z coordinate of the new position for the frame.
|
See Also: getPosition
public void setRotation(Direct3dRMFrame reference, float x, float y,
float z, float theta);
Sets a frame rotating by the given angle around the given vector at each call to the tick or move method. The direction vector [x, y, z] is defined in the reference frame.
Return Value:
No return value.
Parameter | Description |
reference
| The Direct3dRMFrame object to be used as the reference.
|
x
| The x element of the vector, about which rotation occurs.
|
y
| The y element of the vector, about which rotation occurs.
|
z
| The z element of the vector, about which rotation occurs.
|
theta
| The rotation angle, in radians.
|
Remarks:
The specified rotation changes the matrix with every render tick, unlike the addRotation method, which changes the objects in the frame only once.
See Also: addRotation, getRotation
public void setSceneBackground(int c);
Sets the background color of a scene.
Return Value:
No return value.
Parameter | Description |
c
| New color for the background.
|
public void setSceneBackgroundDepth(DirectDrawSurface s);
Specifies a background-depth buffer for a scene.
Return Value:
No return value.
Parameter | Description |
s
| A DirectDrawSurface object that will store the new background depth for the scene.
|
Remarks:
The image must have a depth of 16. If the image and viewport sizes are different, the image is scaled first. For best performance when animating the background-depth buffer, the image should be the same size as the viewport. This enables the depth buffer to be updated directly from the image memory without incurring extra overhead.
See Also: getSceneBackgroundDepth
public void setSceneBackgroundImage(Direct3dRMTexture i);
Specifies a background image for a scene.
Return Value:
No return value.
Parameter | Description |
i
| A Direct3dRMTexture object that will contain the new background scene.
|
Remarks:
If the image is a different size or color depth than the viewport, the image will first be scaled or converted to the correct depth. For best performance when animating the background, the image should be the same size and color depth. This enables the background to be rendered directly from the image memory without incurring any extra overhead.
public void setSceneBackgroundRGB(float r, float g, float b);
Sets the background color of a scene, using an RGB value.
Return Value:
No return value.
Parameter | Description |
r
| The red component of the new color for the background.
|
g
| The green component of the new color for the background.
|
b
| The blue component of the new color for the background.
|
public void setSceneFogColor(int c);
Sets the fog color of a scene.
Return Value:
No return value.
Parameter | Description |
c
| The new color for the fog.
|
public void setSceneFogEnable(int enable);
Sets the fog enable state.
Return Value:
No return value.
Parameter | Description |
enable
| The new fog enable state.
|
public void setSceneFogMode(int c);
Sets the fog mode.
Return Value:
No return value.
Parameter | Description |
c
| The fog mode type.
|
See Also: setSceneFogParams
public void setSceneFogParams(float s, float e, float d);
Sets the current fog parameters for the scene.
Return Value:
No return value.
Parameter | Description |
s
| The fog start point for linear fog mode.
|
e
| The fog end point for linear fog mode. These settings determine the distance from the camera at which the fog effects first become visible and the distance at which the fog reaches its maximum density.
|
d
| The fog density for the exponential fog modes.. This value should be in the range of 0 through 1.
|
See Also: setSceneFogMode
public void setSortMode(int val);
Sets the sorting mode used to process child frames. You can use this method to change the properties of hidden-surface-removal algorithms.
Return Value:
No return value.
Parameter | Description |
val
| One value of the D3DRMSORT_ type, specifying the sorting mode.
|
Remarks:
By default, a frame's initial sort mode is D3DRMSORT_FROMPARENT.
See Also: getSortMode
public void setTexture(Direct3dRMTexture t);
Sets the texture of the frame.
Return Value:
No return value.
Remarks:
The texture is used for meshes in the frame when the material mode is D3DRMMATERIAL_FROMFRAME. To disable the frame's texture, use a null texture.
See Also: getTexture, setMaterialMode
public void setTextureTopology(int wrap_u, int wrap_v);
Defines the topological properties of the texture coordinates across objects in the frame.
Return Value:
No return value.
Parameter | Description |
wrap_u
| A variable that is set to true to map the texture in the u-direction.
|
wrap_v
| A variable that is set to true to map the texture in the v-directions.
|
See Also: getTextureTopology
public void setVelocity(Direct3dRMFrame reference, float x, float y,
float z, int with_rotation);
Sets the velocity of the given frame relative to the reference frame. The frame will be moved by the vector [x, y, z], with respect to the reference frame at each successive call to the tick or move method.
Return Value:
No return value.
Parameter | Description |
reference
| The Direct3dRMFrame object to be used as the reference.
|
x
| The x component of the new velocity for the frame.
|
y
| The y component of the new velocity for the frame.
|
z
| The z component of the new velocity for the frame.
|
with_rotation
| A flag specifying whether the rotational velocity of the object is taken into account when setting the linear velocity. If with_rotation is true, the object's rotational velocity is included in the calculation.
|
See Also: getVelocity
public void setZbufferMode(int val);
Sets the z-buffer mode (that is, whether z-buffering is enabled or disabled).
Return Value:
No return value.
Parameter | Description |
val
| One value of theD3DRMZBUFFER_ type, specifying the z-buffer mode.
|
Remarks:
By default, a frame's initial z-buffer mode is D3DRMZBUFFER_FROMPARENT.
See Also: getZbufferMode
public void transform(D3dVector d, D3dVector s);
Transforms the vector in the s parameter, which is in model coordinates, into world coordinates. The result is returned in the d parameter.
Return Value:
No return value.
Parameter | Description |
d
| A D3dVector object that receives the result of the transformation operation.
|
s
| The D3dVector object that is the source of the transformation operation.
|
See Also: inverseTransform