crystalspace.jbind.interfaces.iengine.movable
Interface iMovable

All Superinterfaces:

iBase, iPointer

All Known Implementing Classes:

csMovable

public interface iMovable

extends iBase

This interface describes the transformation between local object space of some model and world space (i.e. where it is in the world). Movables are attached to mesh objects (use iMeshWrapper->GetMovable()) to get the movable belonging to some mesh. Usually models are defined with the local origin (0,0,0) somewhere in the model. Sometimes in the center or the center-bottom depending on what is easiest. It is important to realize that all position setting routines below operate relative to the local origin of the object. Common problem: some mesh objects (in particular thing) don't allow movement by default for optimization purposes. Changing the movable will not do a lot in that case. To enable moving you have to set the CS_THING_MOVE_OCCASIONAL flags using iThingState->SetMovingOption().

Author:

java wrapper - Quentin Anciaux, original C++ version : http://crystal.sourceforge.net/docs/online/pubapi/structiMovable.php

Method Summary

void	addListener(iMovableListener listener) Add a listener to this movable.
void	clearSectors() Clear the list of sectors.
csVector3	getFullPosition() Get the current position but keep track of hierarchical transformations.
csReversibleTransform	getFullTransform() Construct the full world to object transformation given this transformation and possible parents transformations.
iMovable	getParent() Get the parent movable.
csVector3	getPosition() Get the current position.
iSectorList	getSectors() Get the list of sectors for this entity.
csReversibleTransform	getTransform() Get the world to object tranformation.
long	getUpdateNumber() A number which indicates if the movable has been updated.
boolean	inSector() Return true if we are placed in a sector (i.e. visible).
boolean	isFullTransformIdentity() Return true if the movable transformation is an identity transformation and the (optional) parent of this movable also is has identity transformation.
boolean	isTransformIdentity() This function returns true if the movable transformation is an identity transformation.
void	movePosition(csVector3 v) Relative move.
void	removeListener(iMovableListener listener) Remove a listener from this movable.
void	setParent(iMovable parent) Set the parent movable.
void	setPosition(csVector3 v) Set the transformation vector for this object.
void	setPosition(iSector home, csVector3 v) Set the transformation vector and sector to move to some position.
void	setSector(iSector sector) Initialize the list of sectors to one sector where this thing is.
void	setTransform(csMatrix3 matrix) Set the transformation matrix for this entity.
void	setTransform(csReversibleTransform t) Set the world to object tranformation.
void	transform(csMatrix3 matrix) Relative transform.
void	transformIdentity() Set the transform of this movable to the identity transform (i.e.not moving at all).
void	updateMove() After all movement has been done you need to call UpdateMove() to make the final changes to the entity that is controlled by this movable.

Methods inherited from interface crystalspace.jbind.interfaces.iutil.scf.iBase

decRef, getName, getRefCount, getVersion, incRef, queryInterface, queryInterfaceSafe

Methods inherited from interface crystalspace.jbind.interfaces.iPointer

changePointer, getPointer, isMemoryOwner, setMemoryOwner

Method Detail

addListener

public void addListener(iMovableListener listener)

Add a listener to this movable. This listener will be called whenever the movable changes (when UpdateMove() is called) or right before the movable is destroyed.

Parameters:

listener -

clearSectors

public void clearSectors()

Clear the list of sectors. This basically makes the object invisible as it will not be present in any sector. The mesh will still be present in the engine list of meshes though. This function does not do anything if the parent is not 0. You have to call UpdateMove() after changing the sector information.

getFullPosition

public csVector3 getFullPosition()

Get the current position but keep track of hierarchical transformations. So the returned vector will be the world space coordinate where this object really is.

Returns:

getFullTransform

public csReversibleTransform getFullTransform()

Construct the full world to object transformation given this transformation and possible parents transformations.

Returns:

getParent

public iMovable getParent()

Get the parent movable. This is relevant in case the mesh belonging to this movable is part of a hierarchical transformation.

Returns:

getPosition

public csVector3 getPosition()

Get the current position. Remember that positions are relative to some sector. This function ignores the hierarchical transformation this movable may be part off. If part of a hierarchical transformation this function returns the position relative to the parent.

Returns:

getSectors

public iSectorList getSectors()

Get the list of sectors for this entity. Using this list you can get and set all sectors that this object is in. Note that if an object crosses a portal then you should in theory add every touched sector to this list of sectors. If objects are small then you can get away by not doing this. But it is possible that you will get render/clipping errors. There is a convenience function (iMeshWrapper->PlaceMesh()) which will attempt to find all sectors a mesh is in and update the movable. This will return the sectors of the parent if there is a parent.

Returns:

getTransform

public csReversibleTransform getTransform()

Get the world to object tranformation. This==object and Other==world so This2Other() transforms from object to world space. If you modify this transform you have to call UpdateMove() later. This function ignores the hierarchical transformation this movable may be part off. If part of a hierarchical transformation this function will get the transformation relative to the parent.

Returns:

getUpdateNumber

public long getUpdateNumber()

A number which indicates if the movable has been updated. One can use this number to see if the position of the object has changed since the last time it was checked.

Returns:

inSector

public boolean inSector()

Return true if we are placed in a sector (i.e. visible).

Returns:

isFullTransformIdentity

public boolean isFullTransformIdentity()

Return true if the movable transformation is an identity transformation and the (optional) parent of this movable also is has identity transformation. Only in this case can you know that the object has the same object space coordinates as world space coordinates. Basically this function will return true if GetFullTransform() would return the identity transform.

Returns:

isTransformIdentity

public boolean isTransformIdentity()

This function returns true if the movable transformation is an identity transformation. As soon as the object is moved this function will return false. You can use 'TransformIdentity()' to go back to the identity transform which will again let this flag return true. Note that this flag is only relevant for the transform of this movable and doesn't look at the transforms of the parents. Use IsFullTransformIdentity() for that. The engine and visibility cullers can use this information to optimize stuff a bit. This function ignores the hierarchical transformation this movable may be part off. If part of a hierarchical transformation this function will only test the local transform for identity.

Returns:

movePosition

public void movePosition(csVector3 v)

Relative move. Note that this function will not check for collision detection or portals. This function ignores the hierarchical transformation this movable may be part off. If part of a hierarchical transformation this function will move relative to the parent.

Parameters:

v -

removeListener

public void removeListener(iMovableListener listener)

Remove a listener from this movable.

Parameters:

listener -

setParent

public void setParent(iMovable parent)

Set the parent movable. Usually you don't need to call this function yourselves as it is called automatically whenever you add some mesh to another mesh parent (using iMeshWrapper->GetChildren ()->Add()).

Parameters:

parent -

setPosition

public void setPosition(csVector3 v)

Set the transformation vector for this object. Note that the sectors and orientation are unchanged. You have to call UpdateMove() after changing the position of an object. This function ignores the hierarchical transformation this movable may be part off. If part of a hierarchical transformation this function will set the position relative to the parent.

Parameters:

v -

setPosition

public void setPosition(iSector home,
                        csVector3 v)

Set the transformation vector and sector to move to some position. This call doesn't change the orientation of the model. You have to call UpdateMove() after changing the position of an object. This function ignores the hierarchical transformation this movable may be part off. If part of a hierarchical transformation this function will set the position relative to the parent.

Parameters:

home -

v -

setSector

public void setSector(iSector sector)

Initialize the list of sectors to one sector where this thing is. This is a convenience funcion. Calling this function makes the object visible in this sector. Use GetSectors() if you want to have more control over where the object really is. This function does not do anything if the parent is not 0. You have to call UpdateMove() after changing the sector information.

Parameters:

sector -

setTransform

public void setTransform(csReversibleTransform t)

Set the world to object tranformation. This==object and Other==world for the transform. WARNING: Do not scale objects using the transform in the movable! Several subsystems in Crystal Space (like collision detection and visibility culling) don't work properly if you do that. Instead use iMeshWrapper or iMeshFactoryWrapper->HardTransform() to scale. This function ignores the hierarchical transformation this movable may be part off. If part of a hierarchical transformation this function will set the transformation relative to the parent.

Parameters:

t -

setTransform

public void setTransform(csMatrix3 matrix)

Set the transformation matrix for this entity. You have to call UpdateMove() after changing the transform of an object. WARNING: Do not scale objects using the transform in the movable! Several subsystems in Crystal Space (like collision detection and visibility culling) don't work properly if you do that. Instead use iMeshWrapper or iMeshFactoryWrapper->HardTransform() to scale. This function ignores the hierarchical transformation this movable may be part off. If part of a hierarchical transformation this function will set the transformation relative to the parent.

Parameters:

matrix -

transform

public void transform(csMatrix3 matrix)

Relative transform. This function ignores the hierarchical transformation this movable may be part off. If part of a hierarchical transformation this function will move relative to the parent.

Parameters:

matrix -

transformIdentity

public void transformIdentity()

Set the transform of this movable to the identity transform (i.e.not moving at all). You have to call UpdateMove() after calling this. This function ignores the hierarchical transformation this movable may be part off. If part of a hierarchical transformation this function will only set the local transform to identity.

updateMove

public void updateMove()

After all movement has been done you need to call UpdateMove() to make the final changes to the entity that is controlled by this movable. This is very important! This function is responsible for calling all movement listeners. If you do not call this function then the visibility cullers will not work right (among other things). UpdateMove() will also check for the transform being the identity transform and in that case it will set the identity flag to true.