Tes::Handlers::ShapeHandler Class Reference

Defines the base functionality for MessageHandler objects which add 3D objects to the scene. More...

Inheritance diagram for Tes::Handlers::ShapeHandler:

List of all members.

Public Member Functions
	ShapeHandler (CategoryCheckDelegate categoryCheck)
	Constructor initialising the persistent and transient caches.
override void	Initialise (GameObject root, GameObject serverRoot, MaterialLibrary materials)
	Initialise the shape handler by initialising the shape scene root and fetching the default materials.
override void	Reset ()
	Clear all current objects.
override void	BeginFrame (uint frameNumber, bool maintainTransient)
	Start the frame by flushing transient objects.
override Error	ReadMessage (PacketBuffer packet, BinaryReader reader)
	The primary message handling function.
override Error	Serialise (BinaryWriter writer, ref SerialiseInfo info)
	Serialises the currently active objects in for playback from file.
override void	OnCategoryChange (ushort categoryId, bool active)
	Invoked when an object category changes active state.
virtual Material	LookupMaterialFor (ShapeComponent shape)
	Lookup a material for the given shape created by this handler.
Static Public Member Functions
static void	SetMaterial (Material material, MeshRenderer render, int componentCount, Color colour)
	Set the material for render .
Protected Member Functions
abstract Shapes.Shape	CreateSerialisationShape (ShapeComponent shapeComponent)
	Create a dummy shape object used to generate serialisation messages.
void	ConfigureShape (Shapes.Shape shape, ShapeComponent shapeComponent)
	A helper functio to configure the TES shape to match the Unity object shapeComponent .
virtual Error	SerialiseObjects (BinaryWriter writer, IEnumerator< GameObject > objects, ref uint processedCount)
	Serialises a list of objects to writer
virtual Error	PostSerialiseCreateObject (PacketBuffer packet, BinaryWriter writer, ShapeComponent shape)
	Called after serialising the creation message for an object.
virtual Error	HandleMessage (ushort messageID, PacketBuffer packet, BinaryReader reader)
	Message routing function.
virtual bool	FilterMessage (ushort messageID, uint objectID, ushort category)
	Used to allow filtering of incoming messages.
virtual GameObject	CreateTransient ()
	Instantiates a transient object from the TransientShapeCache
virtual GameObject	CreateObject (uint id)
	Instantiates a persistent object from the ShapeCache.
virtual GameObject	CreateObject ()
	Instantiate a persistent or transient object for this shape.
virtual void	DecodeTransform (ObjectAttributes attributes, Transform transform, ObjectFlag flags=ObjectFlag.None)
	Decodes the transformation embedded in attributes
virtual void	EncodeAttributes (ref ObjectAttributes attr, GameObject obj, ShapeComponent comp)
	Called to extract the current object attributes from an existing object.
virtual void	InitialiseVisual (ShapeComponent obj, Color colour)
	Initialise the visual components (e.g., meshes) for obj .
virtual void	InitialiseMesh (ShapeComponent obj, Mesh sharedMesh, Color colour)
	A convenient overload accepting a single mesh argument.
virtual void	InitialiseMesh (ShapeComponent obj, Mesh[] sharedMeshes, Color colour)
	Sets the render meshes for obj using sharedMeshes .
virtual void	SetColour (GameObject obj, Color colour)
	Sets the colour for obj in using its material(s).
virtual Error	HandleMessage (CreateMessage msg, PacketBuffer packet, BinaryReader reader)
	Message handler for CreateMessage
virtual Error	PostHandleMessage (GameObject obj, CreateMessage msg, PacketBuffer packet, BinaryReader reader)
	Called at end of HandleMessage(CreateMessage, PacketBuffer, BinaryReader), only on success.
virtual Error	HandleMessage (UpdateMessage msg, PacketBuffer packet, BinaryReader reader)
	Message handler for UpdateMessage
virtual Error	PostHandleMessage (GameObject obj, UpdateMessage msg, PacketBuffer packet, BinaryReader reader)
	Called at end of HandleMessage(UpdateMessage, PacketBuffer, BinaryReader), only on success.
virtual Error	HandleMessage (DestroyMessage msg, PacketBuffer packet, BinaryReader reader)
	Message handler for DestroyMessage
virtual Error	PostHandleMessage (GameObject obj, DestroyMessage msg, PacketBuffer packet, BinaryReader reader)
	Called at end of HandleMessage(DestroyMessage, PacketBuffer, BinaryReader) just prior to destroying the object.
virtual Error	HandleMessage (DataMessage msg, PacketBuffer packet, BinaryReader reader)
	Message handler for DataMessage
GameObject	FindObject (uint id)
	Find the persistent object matching the given id
GameObject	RemoveObject (uint id)
	Removes the persistent object matching id from the shape cache without destroying it.
Protected Attributes
TransientShapeCache	_transientCache = null
	Cache for transient objects.
ShapeCache	_shapeCache = null
	Cache for persistent objects.
Properties
GameObject	Root [get]
	Defines the scene root for all objects of this shape type.
MaterialLibrary	Materials [get, set]
	A cache of the material library.
abstract Mesh	SolidMesh [get]
	Defines the mesh object to use for solid instances of this shape.
abstract Mesh	WireframeMesh [get]
	Defines the mesh object to use for wire frame instances of this shape.

---

Detailed Description

Defines the base functionality for MessageHandler objects which add 3D objects to the scene.

The base class handles incoming create, update and destroy messages with consideration given to transient and non-transient and solid or wire frame shapes.

The ShapeHandler class uses a ShapeCache and TransientShapeCache to track persistent and transient objects respectively.

Derivations must define the SolidMesh and WireframeMesh properties to yield the solid and wire frame mesh objects respectively. Derivations must also complete the Shape3D.MeshSetHandler definition by implementing the Shape3D.MeshSetHandler.Name and Shape3D.MeshSetHandler.RoutingID properties.

Derivations may optionally override the default message handling, or parts thereof. Most commonly, the methods DecodeTransform and EncodeAttributes may be overridden.

---

Member Function Documentation

override void Tes::Handlers::ShapeHandler::BeginFrame	(	uint	frameNumber,
		bool	maintainTransient
	)		[inline, virtual]

Start the frame by flushing transient objects.

Parameters:

frameNumber	A monotonic frame number.
maintainTransient	True to disable transient flush.

Reimplemented from Tes::Runtime::MessageHandler.

Reimplemented in Tes::Handlers::Shape3D::MeshHandler.

void Tes::Handlers::ShapeHandler::ConfigureShape	(	Shapes.Shape	shape,
		ShapeComponent	shapeComponent
	)		[inline, protected]

A helper functio to configure the TES shape to match the Unity object shapeComponent .

Parameters:

shape	The shape object to configure to match the Unity representation.
shapeComponent	The Unity shape representation.

virtual GameObject Tes::Handlers::ShapeHandler::CreateObject

(

uint

id

)

[inline, protected, virtual]

Instantiates a persistent object from the ShapeCache.

The new object is assigned the given id

Parameters:

id	The ID of the new object. Must non be zero (for persistent objects).

Returns:

The instantiated object or null on failure.

virtual GameObject Tes::Handlers::ShapeHandler::CreateObject

(

)

[inline, protected, virtual]

Instantiate a persistent or transient object for this shape.

Returns:

An object suitable for use by this shape handler.

Objects created by this method must implement the ShapeComponent component in order to be correctly tracked by the shape cache. The default implementation ensures the following components are present:

• MeshFilter
• MeshRenderer
• ShapeComponent

This method is used to create both and persistent objects. The object is then added to the appropriate cache.

Reimplemented in Tes::Handlers::Shape3D::CapsuleHandler, Tes::Handlers::Shape3D::MeshHandler, Tes::Handlers::Shape3D::MeshSetHandler, Tes::Handlers::Shape3D::PointCloudHandler, and Tes::Handlers::Shape3D::Text3DHandler.

abstract Shapes.Shape Tes::Handlers::ShapeHandler::CreateSerialisationShape

(

ShapeComponent

shapeComponent

)

[protected, pure virtual]

Create a dummy shape object used to generate serialisation messages.

Parameters:

shapeComponent

The component to create a shape for.

Returns:

A shape instance suitable for configuring to generate serialisation messages.

Base classes should implement this method to return an instance of the appropriate Shapes.Shape derivation. For example, the Shape3D.SphereHandler should return a Shapes.Sphere object. See SerialiseObjects(BinaryWriter, IEnumerator<GameObject>, ref uint) for further details.

Implemented in Tes::Handlers::Shape3D::ArrowHandler, Tes::Handlers::Shape3D::BoxHandler, Tes::Handlers::Shape3D::CapsuleHandler, Tes::Handlers::Shape3D::ConeHandler, Tes::Handlers::Shape3D::CylinderHandler, Tes::Handlers::Shape3D::MeshHandler, Tes::Handlers::Shape3D::MeshSetHandler, Tes::Handlers::Shape3D::PlaneHandler, Tes::Handlers::Shape3D::PointCloudHandler, Tes::Handlers::Shape3D::SphereHandler, Tes::Handlers::Shape3D::StarHandler, and Tes::Handlers::Shape3D::Text3DHandler.

virtual GameObject Tes::Handlers::ShapeHandler::CreateTransient

(

)

[inline, protected, virtual]

Instantiates a transient object from the TransientShapeCache

Returns:

The instantiated object or null on failure.

virtual void Tes::Handlers::ShapeHandler::DecodeTransform	(	ObjectAttributes	attributes,
		Transform	transform,
		ObjectFlag	flags = ObjectFlag.None
	)		[inline, protected, virtual]

Decodes the transformation embedded in attributes

Parameters:

attributes	The message attributes to decode.
transform	The transform object to decode into.
flags	The flags associated with the object message. The method considers those related to updating specific parts of the object transformation.

The default implementations makes the following assumptions about attributes :

• The X, Y, Z members define the position.
• The RotationX, RotationY, RotationZ, RotationW define a quaternion rotation.
• The ScaleX, ScaleY, ScaleZ define a scaling in each axis.

This behaviour must be overridden to interpret the attributes differently. For example, the scale members for a cylinder may indicate length and radius, with a redundant Z component.

The flags parameter is used to consider the following ObjectFlag members:

• ObjectFlag.UpdateMode to indentify that only some transform elements are present.
• ObjectFlag.Position
• ObjectFlag.Rotation
• ObjectFlag.Scale

Reimplemented in Tes::Handlers::Shape3D::ArrowHandler, Tes::Handlers::Shape3D::CapsuleHandler, Tes::Handlers::Shape3D::ConeHandler, Tes::Handlers::Shape3D::CylinderHandler, Tes::Handlers::Shape3D::PlaneHandler, Tes::Handlers::Shape3D::SphereHandler, and Tes::Handlers::Shape3D::StarHandler.

virtual void Tes::Handlers::ShapeHandler::EncodeAttributes	(	ref ObjectAttributes	attr,
		GameObject	obj,
		ShapeComponent	comp
	)		[inline, protected, virtual]

Called to extract the current object attributes from an existing object.

Parameters:

attr	Modified to reflect the current state of obj
obj	The object to encode attributes for.
comp	The ShapeComponent of obj

This extracts colour and performs the inverse operation of DecodeTransform This method must be overridden whenever DecodeTransform is overridden.

Reimplemented in Tes::Handlers::Shape3D::ArrowHandler, Tes::Handlers::Shape3D::CapsuleHandler, Tes::Handlers::Shape3D::ConeHandler, Tes::Handlers::Shape3D::CylinderHandler, and Tes::Handlers::Shape3D::Text3DHandler.

virtual bool Tes::Handlers::ShapeHandler::FilterMessage	(	ushort	messageID,
		uint	objectID,
		ushort	category
	)		[inline, protected, virtual]

Used to allow filtering of incoming messages.

Parameters:

messageID	ID of the incoming message.
objectID	ID of the object to which the message relates.
category	Category of the object, or zero if this information is unavailable.

Returns:

True to allow the message to be processed.

The default implementation respects the MessageHandler.ModeFlags values filtering out transient object messages when MessageHandler.ModeFlags.IgnoreTransient is set. Destroy messages are not ignored.

GameObject Tes::Handlers::ShapeHandler::FindObject

(

uint

id

)

[inline, protected]

Find the persistent object matching the given id

Parameters:

id	ID of the object to find.

Returns:

A matching object or null on failure.

virtual Error Tes::Handlers::ShapeHandler::HandleMessage	(	ushort	messageID,
		PacketBuffer	packet,
		BinaryReader	reader
	)		[inline, protected, virtual]

Message routing function.

Parameters:

messageID	The ID of the message.
packet	Packet buffer used to decode the message.
reader	The reader from which additional message data may be read.

Returns:

An error code on failure.

The default implementation handles the following messages: Routes the following messages:

• ObjectMessageID.Create
• ObjectMessageID.Update
• ObjectMessageID.Destroy
• ObjectMessageID.Data

virtual Error Tes::Handlers::ShapeHandler::HandleMessage	(	CreateMessage	msg,
		PacketBuffer	packet,
		BinaryReader	reader
	)		[inline, protected, virtual]

Message handler for CreateMessage

Parameters:

msg	The incoming message.
packet	The buffer containing the message.
reader	The reader from which the message came.

Returns:

An error code on failure.

Creates either a persistent or transient object depending on the incoming message ObjectID. An ID of zero signifies a transient object. Solid or wire shapes are assigned according to the message flags.

Reimplemented in Tes::Handlers::Shape3D::MeshSetHandler, and Tes::Handlers::Shape3D::PointCloudHandler.

virtual Error Tes::Handlers::ShapeHandler::HandleMessage	(	UpdateMessage	msg,
		PacketBuffer	packet,
		BinaryReader	reader
	)		[inline, protected, virtual]

Message handler for UpdateMessage

Parameters:

msg	The incoming message.
packet	The buffer containing the message.
reader	The reader from which the message came.

Returns:

An error code on failure.

Decodes the message transform and colour, updating the existing shape matching the message ObjectID. Only relevant for persistent shapes.

virtual Error Tes::Handlers::ShapeHandler::HandleMessage	(	DestroyMessage	msg,
		PacketBuffer	packet,
		BinaryReader	reader
	)		[inline, protected, virtual]

Message handler for DestroyMessage

Parameters:

msg	The incoming message.
packet	The buffer containing the message.
reader	The reader from which the message came.

Returns:

An error code on failure.

Finds and destroys the object matching the message ObjectID.

virtual Error Tes::Handlers::ShapeHandler::HandleMessage	(	DataMessage	msg,
		PacketBuffer	packet,
		BinaryReader	reader
	)		[inline, protected, virtual]

Message handler for DataMessage

Parameters:

msg	The incoming message.
packet	The buffer containing the message.
reader	The reader from which the message came.

Returns:

ErrorCode.UnsupportedFeature

Not implemented to properly handle the message, returning an appropriate error code.

Reimplemented in Tes::Handlers::Shape3D::MeshHandler, and Tes::Handlers::Shape3D::PointCloudHandler.

override void Tes::Handlers::ShapeHandler::Initialise	(	GameObject	root,
		GameObject	serverRoot,
		MaterialLibrary	materials
	)		[inline, virtual]

Initialise the shape handler by initialising the shape scene root and fetching the default materials.

Parameters:

root	The 3rd Eye Scene root object.
serverRoot	The server scene root (transformed into the server reference frame).
materials	Material library from which to resolve materials.

Reimplemented from Tes::Runtime::MessageHandler.

Reimplemented in Tes::Handlers::Shape3D::MeshHandler, Tes::Handlers::Shape3D::MeshSetHandler, Tes::Handlers::Shape3D::PointCloudHandler, and Tes::Handlers::Shape3D::Text3DHandler.

virtual void Tes::Handlers::ShapeHandler::InitialiseMesh	(	ShapeComponent	obj,
		Mesh	sharedMesh,
		Color	colour
	)		[inline, protected, virtual]

A convenient overload accepting a single mesh argument.

Parameters:

obj	The object to initialise visuals for.
sharedMesh	The mesh to render with.
colour	Primary rendering colour.

Maps to the overload: InitialiseMesh(ShapeComponent, Mesh[], Color).

virtual void Tes::Handlers::ShapeHandler::InitialiseMesh	(	ShapeComponent	obj,
		Mesh[]	sharedMeshes,
		Color	colour
	)		[inline, protected, virtual]

Sets the render meshes for obj using sharedMeshes .

Parameters:

obj	The object to initialise visuals for.
sharedMeshes	The meshes to render with.
colour	Primary rendering colour.

This function sets sharedMeshes as a set of shared mesh resources to render obj with. When there is one element in sharedMeshes , the mesh and material are set on the MeshFilter and MeshRenderer belonging to obj itself. When multiple items are given, the children of obj are used instead. This means the number of children must match the number of elements in sharedMeshes .

The materials used are attained via LookupMaterialFor(ShapeComponent) where the ShapeComponent belongs to obj .

virtual void Tes::Handlers::ShapeHandler::InitialiseVisual	(	ShapeComponent	obj,
		Color	colour
	)		[inline, protected, virtual]

Initialise the visual components (e.g., meshes) for obj .

Parameters:

obj	The object to initialise visuals for.
colour	Primary rendering colour.

The default implementation resolves a single mesh using SolidMesh or WireframeMesh (depending on ShapeComponent.Wireframe) and invokes InitialiseMesh(ShapeComponent, Mesh, Color).

Reimplemented in Tes::Handlers::Shape3D::CapsuleHandler.

virtual Material Tes::Handlers::ShapeHandler::LookupMaterialFor

(

ShapeComponent

shape

)

[inline, virtual]

Lookup a material for the given shape created by this handler.

Parameters:

shape

The shape to lookup a material for.

Returns:

The material for that shape.

Respects various ObjectFlag values.

override void Tes::Handlers::ShapeHandler::OnCategoryChange	(	ushort	categoryId,
		bool	active
	)		[inline, virtual]

Invoked when an object category changes active state.

Parameters:

categoryId	The category changing state.
active	The new active state.

Handlers should only ever visualise objects in active categories.

Implements Tes::Runtime::MessageHandler.

virtual Error Tes::Handlers::ShapeHandler::PostHandleMessage	(	GameObject	obj,
		DestroyMessage	msg,
		PacketBuffer	packet,
		BinaryReader	reader
	)		[inline, protected, virtual]

Called at end of HandleMessage(DestroyMessage, PacketBuffer, BinaryReader) just prior to destroying the object.

The object will still be destroyed.

Parameters:

obj	The object being destroyed.
msg	The incoming message.
packet	The buffer containing the message.
reader	The reader from which the message came.

Returns:

An error code on failure.

Reimplemented in Tes::Handlers::Shape3D::MeshHandler, Tes::Handlers::Shape3D::MeshSetHandler, and Tes::Handlers::Shape3D::PointCloudHandler.

virtual Error Tes::Handlers::ShapeHandler::PostHandleMessage	(	GameObject	obj,
		UpdateMessage	msg,
		PacketBuffer	packet,
		BinaryReader	reader
	)		[inline, protected, virtual]

Called at end of HandleMessage(UpdateMessage, PacketBuffer, BinaryReader), only on success.

Parameters:

obj	The object being updated.
msg	The incoming message.
packet	The buffer containing the message.
reader	The reader from which the message came.

Returns:

An error code on failure.

Reimplemented in Tes::Handlers::Shape3D::Text3DHandler.

virtual Error Tes::Handlers::ShapeHandler::PostHandleMessage	(	GameObject	obj,
		CreateMessage	msg,
		PacketBuffer	packet,
		BinaryReader	reader
	)		[inline, protected, virtual]

Called at end of HandleMessage(CreateMessage, PacketBuffer, BinaryReader), only on success.

Parameters:

obj	The newly created message.
msg	The incoming message.
packet	The buffer containing the message.
reader	The reader from which the message came.

Returns:

An error code on failure.

Reimplemented in Tes::Handlers::Shape3D::MeshHandler, and Tes::Handlers::Shape3D::Text3DHandler.

virtual Error Tes::Handlers::ShapeHandler::PostSerialiseCreateObject	(	PacketBuffer	packet,
		BinaryWriter	writer,
		ShapeComponent	shape
	)		[inline, protected, virtual]

Called after serialising the creation message for an object.

This allows follow up data messages to be serialised.

Parameters:

packet
writer
shape

Returns:

override Error Tes::Handlers::ShapeHandler::ReadMessage	(	PacketBuffer	packet,
		BinaryReader	reader
	)		[inline, virtual]

The primary message handling function.

Parameters:

packet
reader

Returns:

Invokes HandleMessage(ushort, PacketBuffer, BinaryReader)

Implements Tes::Runtime::MessageHandler.

GameObject Tes::Handlers::ShapeHandler::RemoveObject

(

uint

id

)

[inline, protected]

Removes the persistent object matching id from the shape cache without destroying it.

Parameters:

id	ID of the object to find.

Returns:

A matching object or null on failure.

override Error Tes::Handlers::ShapeHandler::Serialise	(	BinaryWriter	writer,
		ref SerialiseInfo	info
	)		[inline, virtual]

Serialises the currently active objects in for playback from file.

Parameters:

writer	The write to serialise to.
info	Statistics

Returns:

An error code on failure.

Implements Tes::Runtime::MessageHandler.

virtual Error Tes::Handlers::ShapeHandler::SerialiseObjects	(	BinaryWriter	writer,
		IEnumerator< GameObject >	objects,
		ref uint	processedCount
	)		[inline, protected, virtual]

Serialises a list of objects to writer

Parameters:

writer	The writer to serialise to.
objects	The object to write.
processedCount	Number of objects processed.

Returns:

An error code on failure.

Default serialisation uses the following logic on each object:

• Call CreateSerialisationShape(ShapeComponent) to create a temporary shape to match the unity object
• Call Shapes.Shape.WriteCreate(PacketBuffer) to generate the creation message and serialise the packet.
• For complex shapes, call Shapes.Shape.WriteData(PacketBuffer, ref uint) as required and serialise the packets.

Using the Shapes.Shape classes ensures serialisation is consistent with the server code and reduces the code maintenance to one code path.

virtual void Tes::Handlers::ShapeHandler::SetColour	(	GameObject	obj,
		Color	colour
	)		[inline, protected, virtual]

Sets the colour for obj in using its material(s).

Parameters:

obj	The object to set the colour of. Must belong to this handler.
colour	The target colour.

static void Tes::Handlers::ShapeHandler::SetMaterial	(	Material	material,
		MeshRenderer	render,
		int	componentCount,
		Color	colour
	)		[inline, static]

Set the material for render .

Parameters:

material	The material to instance.
render	The target object.
componentCount	The number of mesh components. Instance this many materials.
colour	The main render colour.

---

Property Documentation

MaterialLibrary Tes::Handlers::ShapeHandler::Materials [get, set]

A cache of the material library.

Set in Initialise(GameObject, GameObject, MaterialLibrary).

GameObject Tes::Handlers::ShapeHandler::Root [get]

Defines the scene root for all objects of this shape type.

The root for objects of this shape.

abstract Mesh Tes::Handlers::ShapeHandler::SolidMesh [get]

Defines the mesh object to use for solid instances of this shape.

Returns:

The solid mesh for this shape.

Reimplemented in Tes::Handlers::Shape3D::ArrowHandler, Tes::Handlers::Shape3D::BoxHandler, Tes::Handlers::Shape3D::CapsuleHandler, Tes::Handlers::Shape3D::ConeHandler, Tes::Handlers::Shape3D::CylinderHandler, Tes::Handlers::Shape3D::MeshHandler, Tes::Handlers::Shape3D::MeshSetHandler, Tes::Handlers::Shape3D::PlaneHandler, Tes::Handlers::Shape3D::PointCloudHandler, Tes::Handlers::Shape3D::SphereHandler, Tes::Handlers::Shape3D::StarHandler, Tes::Handlers::Shape3D::Text3DHandler, and Tes::PyramidHandler.

abstract Mesh Tes::Handlers::ShapeHandler::WireframeMesh [get]

Defines the mesh object to use for wire frame instances of this shape.

Returns:

The wire frame mesh for this shape.

Reimplemented in Tes::Handlers::Shape3D::ArrowHandler, Tes::Handlers::Shape3D::BoxHandler, Tes::Handlers::Shape3D::CapsuleHandler, Tes::Handlers::Shape3D::ConeHandler, Tes::Handlers::Shape3D::CylinderHandler, Tes::Handlers::Shape3D::MeshHandler, Tes::Handlers::Shape3D::MeshSetHandler, Tes::Handlers::Shape3D::PlaneHandler, Tes::Handlers::Shape3D::PointCloudHandler, Tes::Handlers::Shape3D::SphereHandler, Tes::Handlers::Shape3D::StarHandler, Tes::Handlers::Shape3D::Text3DHandler, and Tes::PyramidHandler.

---

The documentation for this class was generated from the following file:

• ShapeHandler.cs