SceneGraph

Home About XEngine Engine API SceneGraph Changelog Programming Guide

Index

| Scene Description Language | camera | directory | eventmessage | geometry | group | input | light | node | primitives | root | spinner | transformation | user |

Camera

Derived from: Node3D
Class name: Camera3D
Description: It implements a view to the virtual world. It can be configured to follow a specific user or any other node, to be left standing alone or to be transformed as a normal geometric node in a kinematic chain. Multiple cameras can be defined but only one acts as the primary (rendered) output.

 

Function List

Name XE_camera_set_aperture
Arguments int node_id, float aperture
Return Type bool
Description Sets the camera aperture

Parameters:
- node_id, the node's id
- aperture, the camera aperture in degrees (Default value is 60 degrees)

Returns true if the node id was found
Notes:  

Name XE_camera_get_aperture
Arguments int node_id, float& aperture
Return Type bool
Description Retrieves the camera aperture

Parameters:
- node_id, the node's id
- aperture, the camera aperture in degrees

Returns true if the node id was found
Notes:  

Name XE_camera_set_near_range
Arguments int node_id, float near_range
Return Type bool
Description Sets the camera near range

Parameters:
- node_id, the node's id
- near_range, the camera near range (Default value is 1.0)

Returns true if the node id was found
Notes:  

Name XE_camera_get_near_range
Arguments int node_id, float&near_range
Return Type bool
Description Retrieves the camera near range

Parameters:
- node_id, the node's id
- near_range, the camera near range

Returns true if the node id was found
Notes:  

Name XE_camera_set_far_range
Arguments int node_id, float far_range
Return Type bool
Description Sets the camera far range

Parameters:
- node_id, the node's id
- far_range, the camera far_range (Default value is 500.0)

Returns true if the node id was found
Notes:  

Name XE_camera_get_far_range
Arguments int node_id, float& far_range
Return Type bool
Description Retrieves the camera far range

Parameters:
- node_id, the node's id
- far_range, the camera far range

Returns true if the node id was found
Notes:  

Name XE_camera_set_follow
Arguments int camera_node_id, int node_id
Return Type bool
Description Sets which node the camera follows (usually a user node)

Parameters:
- camera_node_id, the camera node's id
- node_id, the node's id the camera will follow (Default value is null)

Returns true if both nodes' ids were found
Notes:  

Name XE_camera_get_follow
Arguments int camera_node_id, int& node_id
Return Type bool
Description Retrieves the camera follower's node id

Parameters:
- camera_node_id, the camera node's id
- node_id, the node's id the camera will follow

Returns true if both nodes' ids were found, otherwise node_id is set to -1
Notes:  

Name XE_camera_set_primary
Arguments int node_id, bool primary
Return Type bool
Description Sets whether this camera is the primary camera

Parameters:
- node_id, the node's id
- primary, a flag indicating whether this is the primary camera (By default, if only one camera is available, the it is the primary camera)

Returns true if the node id was found
Notes:  

Name XE_camera_get_primary
Arguments int node_id, bool& primary
Return Type bool
Description Retrieves the camera primary status

Parameters:
- node_id, the node's id
- primary, a flag indicating whether this is the primary camera

Returns true if the node id was found
Notes:  

Name XE_camera_get_direction
Arguments int node_id, float& x, float& y, float& z
Return Type bool
Description Gets a 3D vector with the camera's direction

Parameters:
- node_id, the node's id
- x, the x value of the normalized direction vector in world coordinates
- y, the y value of the normalized direction vector in world coordinates
- z, the z value of the normalized direction vector in world coordinates

Returns true if the node id was found
Notes:  

Name XE_camera_get_view
Arguments int node_id, float* mat
Return Type bool
Description Gets the camera's view transformation

Parameters:
- node_id, the node's id
- mat, a pointer to a 16 float array containing the camera's view matrix

Returns true if the node id was found
Notes:  

Name XE_camera_get_projection
Arguments int node_id, float* mat
Return Type bool
Description Gets the camera's projection transformation

Parameters:
- node_id, the node's id
- mat, a pointer to a 16 float array containing the camera's projection matrix

Returns true if the node id was found
Notes:  

 

Scene Description Language Declaration

XML node name camera
Placement: Anywhere
Description:

It implements a view to the virtual world. It can be configured to follow a specific user or any other node, to be left standing alone or to be transformed as a normal geometric node in a kinematic chain. Multiple cameras can be defined but only one acts as the primary (rendered) output. If a single camera has been declared in the scene file, it is automatically bound as the primary one. If no camera has been declared, one is automatically generated and attached to the user.

Special notes: -
Inherited attributes: name, active, visible
New attributes:
attribute type description
aperture FLOAT The full end-to-end aperture of the camera lens in degrees, corresponding to the vertical direction. The horizontal apperure is determined by the aspect ratio of the window. Default value is 60.0 (degrees).
near FLOAT The near clipping plane distance. Must be a positive number. Default value is 1.0.
far FLOAT The far clipping plane distance. Must be a positive number. Default value is 500.0.
primary BOOLEAN Denotes that this camera is currently active for output in the framebuffer.
follow STRING The name of the node to attach the camera to. Usually this is a user node, but can actually be anything.
Events:
event name condition
follow Issued whenever the camera attachment is changed.
Inherited events: -
New messages:
attribute value description
follow STRING Follow the named node, if the name given is valid.
aperture FLOAT Change the aperture of the camera
near FLOAT Change the near clipping plane distance of the camera.
far FLOAT Change the far clipping plane distance of the camera.
Inherited messages: -
Redefined messages: -
Obsolete messages: active, visible, hide, show, deactivate, enable, activate, disable

Example

<world ambient="0.3 0.3 0.3" background="0.2 0.2 0.2">
  
    <camera name="first_person" aperture="50.0" 
            near="2.0" far="1000" follow="Myself" primary="true">
    </camera> 

    <transformation name="environment" scale="1.0,1.0,1.0" translation="0,0,-10">
        
        <object name="geom2" file="arena.obj"></object>
    
    </transformation>
 
    <user name="Myself" control="navigate" speed="2.0" turn="0.5"
          position="0,10,100" lookat="0,10,0" input="MouseKeyboard">
    </user>

    <input name="MouseKeyboard" devicename="device0">
    </input>
</world>

Last updated: 3 Jun. 2013