Virtual Stage

Revision as of 20:16, 11 November 2011

Overview

A virtual stage is a separate 3D world that can be created for displaying assets independent of the world. The stage renders to a texture which can then be used by the GUI. These are useful for a separate window on things like inventory items, etc. These created textures may also be used for objects in the world.

Virtual Stages are not persistent -- they are created and destroyed as needed.

As of this writing, the primary uses for Virtual Stages are the crafting system and character manager. These are places in the game where it is desired to see 3D objects, but without them being in the actual game world. The instances come from assets stored in Prop Buckets, but it is not necessary to use the same bucket for each one.

You can create and manipulate a virtual stage with various GUIFunctions.

Related Functions

There are certain basic categories of functions to deal with a Virtual Stage:

• Creating, destroying, and resizing the stage
• Dealing with Stage Instances
• Getting and setting camera vectors
• Getting and setting light vectors

StageSaveTexture(stageNameParam as String, FQNparam as String, formatParam as String) as Boolean

StageSaveTexture accepts at a minimum the following image formats:

• BMP
• JPG
• TGA
• PNG
• DDS
• PPM
• DIB
• HDR
• PFM

Stage Manipulation

Create Stage

Creates a new Virtual Stage for rendering, with a render target texture of the specified width and height. On some video cards, width and height should both be powers of 2 (64, 128, 256, 512 or 1024). Returns false if the stage already exists or width/height values are invalid.

StageCreate(stageName as string, width as int, height as int) as boolean

Destroy Stage

Destroys a stage. If a stage is not destroyed with this command, it will hang around until the client is shut down. There is no penalty for attempting to destroy a stage that was already deleted.

StageDestroy(stageName as string)

Resize Stage

Resizes the render target texture of an existing Virtual Stage. Returns false if the stage does not exist, or width/height values are invalid.

StageResize(stageName as string, width as int, height as int) as boolean

Change Stage Backdrop Color

Changes the backdrop color for a Virtual Stage. Color is specified by string in the format #R,G,B,A where each value is a float from 0 to 1. Alpha determines the stage's full-scene bloom (0=no bloom, 1=max). Returns false if the stage does not exist.

StageSetBackdropColor(stageName as string, color as string) as boolean

Copy Character Into Virtual Stage

This function copies an entire character, including their inventory, to a virtual stage. One possible use of this function might be to display a character's invetory. As of this writing, it does not copy objects that are "held" by the character. To move those items as well, a separate prop bucket is needed.

CopyCharacterIntoVirtualStage(original as NodeRef of Class HBNode, stagename as String) as NodeRef of Class HBNode

Stage Camera

Get Stage Camera Zoom

Returns a floating point number which indicates how close the stage's camera is zooming in.

StageGetZoom(stageName as string) as float

Set Stage Camera Zoom

Sets the zoom factor for the Virtual Stage's camera. Returns false if the stage does not exist. The larger the number, the smaller the object on the stage appears. Default value is 1.0, which means display the object at its normal world size, as if you were 1 meter away. So a zoom of 10.0 would mean display the object as though you were 10 meters away. There are no minimum or maximum values, though a negative value would mean being on the other side of the object, and a value of 0 would mean being inside of it!

StageSetZoom(stageName as string, zoom as float) as boolean

Set AutoZoom

Tells the Virtual Stage to automatically set its zoom factor to fit everything in its scene. Returns false if the stage does not exist.

StageAutoZoom(stageName as string) as boolean

Get Camera Rotation

Returns a vector with the direction that the camera is currently pointing from, in (pitch, yaw, roll) degrees.

StageGetRotation(stageName) as vector3

Set Camera Rotation

Sets the camera rotation for the specified Virtual Stage, in (pitch,yaw,roll) format, in degrees. The camera automatically positions itself so that it faces (0,0,0) whatever its rotation may be. Returns false if the stage does not exist.

StageSetRotation(stageName as string, rotation as vector3) as boolean

Note: In this context, rotation does not mean speed of rotation (that would be delta). It means the relative angle that the camera is pointing from. For example: If the stage is looking at a model of a coffeecup, and rotation is set to (0,90,0), then the view of the coffeecup will change so it is being looked at from the righthand side.

Set Camera Rotation Delta

Sets the amount by which that the Virtual Stage's camera will rotate each second, in degrees. Returns false if the stage does not exist. So if the delta is 90, then the image rotates 90 degrees every second, and would turn completely around every 4 seconds. For reference, at your typical car show where a car is on a big pedestal that is rotating, the delta might be 10. 10 degrees per second, or a full rotation in 36 seconds.

StageSetDeltaRotation(stageName as string, deltaRotation as vector3) as boolean

Set Auto Center on Objects

Client function. If set to true, the virtual stage camera will focus on the center of the stage's collective bounding box; otherwise the camera will focus on (0,0,0).

StageSetAutoCenterOnObjects(stageName as string, autoCenter as boolean)

Camera Forward Vector

This function takes a stage name, and returns a vector3 value which points in the direction that the camera is currently looking.

StageGetCameraForwardVector(stageName as string) as vector3

Camera Right Vector

This function takes a stage name, and returns a vector3 value which points 90 degrees to the right of where the camera is looking. For example, if you face forward and then lift your right arm to point to the right, where you are looking is the forward vector, and where your right arm is pointing is the right vector. As the camera angle changes, the right vector moves with it.

StageGetCameraRightVector(stageName as string) as vector3

Camera Up Vector

This function takes a stage name, and returns a vector3 value which points up at 90 degrees from (points in the direction??) the direction that the camera is currently looking. For example, if you face forward and look straight ahead, where you are looking is the Forward Vector, and a line from your toes to the crown of your head is the up vector. This vector stays at 90 degrees, so as the camera angle changes, the up vector changes accordingly.

StageGetCameraUpVector(stageName as string) as vector3

Stage Lighting

Get Directional Light

Gets the properties of the Virtual Stage's directional light. The colors' alpha is ignored. Returns false if the stage does not exist. A Directional Light is a simulated "sun" that tells the game world which direction that light is coming from (or to be specific, which way that light is going). For example, a direction vector of (0,-1,0) would mean that light was coming down from directly overhead. A direction vector of

StageGetDirectionalLight(stageName as string, ambientColor as string, diffuseColor as string, lightDirection as vector3) as boolean

Set Directional Light

Sets the properties of the Virtual Stage's directional light. The colors' alpha is ignored. Returns false if the stage does not exist.

StageSetDirectionalLight(stageName as string, ambientColor as string, diffuseColor as string, lightDirection as vector3) as boolean

Set Fog Color

Sets the distance-based fog color for the Virtual Stage, in #R,G,B,A format where each value is a float from 0 to 1. Alpha determines the thickness of the fog. Returns false if the stage does not exist.

StageSetFog(stageName as string, fogColor as string) as boolean

Stage Instances

Activate instance

Activates the specified node, making it renderable. If the stage name is "", the node is rendered in the Area. Otherwise, it is rendered by the specified Virtual Stage. If the node or stage could not be found, this function returns a value of FALSE. If the instance is successfully activated, this function returns a value of TRUE.

ActivateInstance(instance as noderef, stageName as string) as boolean
ActivateInstance(instanceID as ID, stageName as string) as boolean

Inactivate instance

Inactivates the specified node, making it unrenderable. Returns FALSE if the node could not be found.

InactivateInstance(instance as noderef) as boolean

Get Instances on Stage

Will generate a list of all of the instances which are currently on a stage. Will generate an error if not called on a valid stage name.

StageGetInstances(stageName as string, instanceList references list of noderef) as boolean

Examples

Suppose you wish to place a directional light which shines onto the stage from a 45-degree angle off the horizon. To set the directional light, first this angle must be converted into vector3 format. This is done with the Spherical2XYZ() exposed function:

LightDirection as vector3
ambient as string = "#.2, .2, .2, 1"   // This is the "grey" color
diffuse as string = "#1,1,1,1"         // This is a "white" color
 
Spherical2XYZ(0.0, 45.0, 1.0, LightDirection)
StageSetDirectionalLight("Stage", ambient, diffuse, LightDirection)  // Gives a little bit of ambient light, and a lot of diffuse

The following code will create a Virtual Stage and copy the character into it. The camera is adjusted so it's looking at the front of the character, centered on the character and zoomed out so the entire character it visible. Then a GUIPanel is created to show the virtual stage.

//setup the virtual stage
stageName as String = "ExampleStage"
StageCreate(stageName, 256, 256)
CopyCharacterIntoVirtualStage(GetAccountID(), stageName)
StageSetRotation(stageName, (0,180,0))
StageAutoZoom(stageName)
StageSetAutoCenterOnObjects(stageName, true)
 
//create a GUI panel to show the virtual stage
panel as NodeRef of Class GUIControl = CreateNodeFromPrototype("_panel")
panel.build = true
panel.name = stageName
panel.size.x = 256
panel.size.y = 256
panel.texture = ":" + stageName

See Also

• Prop Buckets
• GUIFunctions
• Vector Functions
• GUIXML
• GUI

• Privacy policy
• About HEWIKI
• Disclaimers

• Copyright (c) 2006-2013 Idea Fabrik Plc. All Rights Reserved.
• HeroCloud is a registered trademark of IdeaFabrik Plc, all rights reserved
• HeroEngine is a registered trademark of IdeaFabrik Plc, all rights reserved