Static Public Member Functions | Private Member Functions | Private Attributes | Static Private Attributes

VR3Scene Class Reference

The scene class. More...

#include <VR3Scene.h>

Collaboration diagram for VR3Scene:
Collaboration graph
[legend]

List of all members.

Public Member Functions

Constructor and Destructor
 VR3Scene (GLsizei width, GLsizei height, GLfloat fovy, GLfloat znear=VR3SC_DEF_ZNEAR, GLfloat zfar=VR3SC_DEF_ZFAR)
 Scene constructor.
 ~VR3Scene ()
 Scene destructor.
Get and Set Scene parameters
void SetClearColor (GLfloat r, GLfloat g, GLfloat b)
 Sets the background cleaning color.
void SetClearColor (const GLfloat *color)
 Sets the background cleaning color.
VR3CameraGetCurrentCamera ()
 Gets the currently active camera.
void SetActiveCamera (int id)
 Sets the currently active camera.
void SetLightPosition (int id, GLfloat x, GLfloat y, GLfloat z)
 Sets the position of a light.
void SetLightPosition (int id, const GLfloat *v)
 Sets the position of a light.
void GetLightPosition (int id, GLfloat *p)
 Gets the position of a light.
void SetLightColor (int id, int color, GLfloat r, GLfloat g, GLfloat b)
 Sets the color of a light component.
void GetLightColor (int id, int color, GLfloat *c)
 Gets the color of a light component.
GLint GetActiveLights (bool *fa)
 Gets an array of flags stating which lights are active.
void SetBackground (const char *file_name, bool fl_skybox=false)
 Loads a background from a file.
VR3TextureGetBackground ()
 Gets the current background.
void EnvironmentMapping (const char *diff_file, const char *spec_file)
 Enables the Image-Based Lighting mode specifying which cube maps to use.
VR3TextureGetEnvMap (GLint map)
 Gets one of the current environment maps as a VR3Texture object.
GLint GetEnvMappingMode ()
 Gets the current environment mapping mode.
void SetFrameRate (GLfloat fps)
 Sets the target frame rate.
GLfloat GetFrameRate ()
 Gets the current frame rate.
GLint GetNumPolys ()
 Gets the current number of polygons in meshes.
void AddPolys (GLint polys)
 Add a number to the current polygons counter.
bool HasBegun ()
 Checks if the scene has begun.
Enable and Disable Scene Components
void Enable (int feature, int optional_param=0)
 Enables a specific scene feature.
void Disable (int feature, int optional_param=0)
 Disables a specific scene feature.
bool IsEnabled (int feature, int optional_param=0)
 Checks if a particular scene feature is active.
bool CheckVFCulling ()
 Checks whether view frustum culling is enabled or not.
Visualization Functions
void UpdateDrawRegion (GLsizei w, GLsizei h)
 Updates the current global draw region size.
Scene Properties Discovery Function
const VR3SceneShaderParamsFetchParameters ()
 Scene properties discovery function.

Static Public Member Functions

static VR3SceneGetActiveScene ()
 Gets the current VR3Scene object.

Private Member Functions

 VR3Scene (const VR3Scene &)
 Disable default copy constructor.
VR3Sceneoperator= (const VR3Scene &)
 Disable default assignment operator.

Private Attributes

bool m_beginendblock
 Flag stating if we are inside a Begin()..End() block.
long m_time
 Last time value extracted (used for frame rate regulation)
long m_starttime
 Framerate computation start time (used every 100 frames)
long m_framecounter
 Frame counter for framerate computation.
int m_polycounter
 Poligons counter.
VR3SceneShaderParams m_shadparams
 Shader parameters values.
Scene Properties
VR3Camera m_cameras [VR3SC_NUM_CAMERAS]
 Available cameras in the scene.
VR3Cameram_current_camera
 Currently active camera.
VR3Light m_lights [VR3SC_NUM_LIGHTS]
 Available lights in the scene.
bool m_face_culling
 Backface culling enabled flag.
bool m_vf_culling
 View frustum culling enabled flag.
VR3Background m_background
 Scene background.
int m_polygons
 Continuously computed number of polygons.
Image-Based Lighting (Environment Mapping) parameters

Environment Mapping (Image Based Lighting) may be activated or deactivated by the user. When activated, ordinary lights will not be used to shade meshes during rendering but only to compute shadows when needed. Mesh shading will be performed by sampling two distinct environment maps.

GLint m_env_mode
 Environment mapping mode.
VR3Texturem_env_specular
 Specular lighting environment map.
VR3Texturem_env_diffuse
 Diffuse lighting environment map (convolution of the above map)
Visualization Properties
GLsizei m_totdrawregion [2]
 Global viewport size (window size)
GLint m_minframetime
 Minimum (target) frame time (in milliseconds)
GLfloat m_framerate
 Continuously computed frame rate.

Static Private Attributes

static VR3Scenems_activescene
 Pointer to the currently active VR3Scene object.

Rendering Begin and End Functions

void RealBegin (GLsizei width, GLsizei height, VR3Camera *cam, int flags)
 Starts the scene rendering.
void Begin (VR3Camera *cam=0, int flags=0)
 Starts the scene rendering.
void BeginAbs (GLint x, GLint y, GLsizei w, GLsizei h, VR3Camera *cam=0, int flags=0)
 Starts the scene rendering, specifying an output absolute screen region.
void BeginRel (GLfloat x, GLfloat y, GLfloat w, GLfloat h, VR3Camera *cam=0, int flags=0)
 Starts the scene rendering, specifying an output relative screen region.
void BeginFBO (VR3FBO *fbo, VR3Camera *cam=0, int flags=0)
 Starts the scene rendering, specifying the VR3FBO where to render the scene.
void End ()
 Ends the scene rendering.

Shader Parameters Update Functions

void UpdateLightParams ()
 Updates the scene light uniform parameters to be used by the shaders.
void UpdateMatrices (GLsizei width, GLsizei height)
 Updates the projection and viewing matrix to be used by the shaders.
void StoreUniforms (GLsizei width, GLsizei height)
 Sets all uniform parameters consumed by the shaders once.

Detailed Description

The scene class.

This class allows to manage global scene properties and wraps management of cameras and lights in the scene. This class also provides the basic functions to begin and end a rendering section (Begin() to start and End() to finish). All the graphical commands have to be called inside a Begin()...End() block. Typically, just a single instance of the VR3Scene object will be used, representing a single scene where moving objects and lights are represented, a scene object stores informations about scene lights, cameras, background and environment maps. Nevertheless, it is possible to create multiple scene objects to represent different scenes to be used at different times or in different regions of the GL window.

The scene also manages a set of features that may be enabled or disabled by the user, the available features are the following:

Definition at line 92 of file VR3Scene.h.


Constructor & Destructor Documentation

VR3Scene::VR3Scene ( const VR3Scene  ) [private]

Disable default copy constructor.

VR3Scene::VR3Scene ( GLsizei  width,
GLsizei  height,
GLfloat  fovy,
GLfloat  znear = VR3SC_DEF_ZNEAR,
GLfloat  zfar = VR3SC_DEF_ZFAR 
)

Scene constructor.

Builds a new scene object using a global viewport of the specified size and using cameras having the specified fovy and near/far clipping planes.

Parameters:
[in]width,heightThe viewport size in pixel
[in]fovyThe cameras field of view (y axis)
[in]znear,zfarThe clipping planes distances
VR3Scene::~VR3Scene (  )

Scene destructor.

It also sets a null active scene if this was the active one.


Member Function Documentation

void VR3Scene::AddPolys ( GLint  polys ) [inline]

Add a number to the current polygons counter.

The number of polygons is computed for each Begin()...End() block, considering the objects that are drawn inside it. During object drawing, the VR3Mesh objects will call this function in order to notify the active VR3Scene that some polygons have been drawn.

Parameters:
[in]polysNumber of polygons drawn

Definition at line 490 of file VR3Scene.h.

void VR3Scene::Begin ( VR3Camera cam = 0,
int  flags = 0 
)

Starts the scene rendering.

Indicates the beginning of the visual scene description. Once started, the scene must be finalized with the End() function. All the graphical commands which produce a visual output must be inserted inside a Begin()..End() block. It is possible to have several consecutive Begin()..End() blocks. It is also possible to pass a VR3Camera object: its projection and viewing parameters are used throughout the scene and is made the current active camera..

Parameters:
[in]camA reference to a VR3Camera object (if 0 the current active camera is used instead)
[in]flagsA combination of one or more flags

void VR3Scene::BeginAbs ( GLint  x,
GLint  y,
GLsizei  w,
GLsizei  h,
VR3Camera cam = 0,
int  flags = 0 
)

Starts the scene rendering, specifying an output absolute screen region.

This function behaves like the Begin() function, but in addition specifies a subregion of the screen, expressed in window coordinates, where the scene is drawn. Combined with other SceneBegin()..SceneEnd() blocks, it allows to realize split-screen or multi-screen applications. It is also possible to pass a VR3Camera object: it's projection and viewing parameters are used throughout the scene and is made the current active camera.

Parameters:
[in]x,yThe window coordinates of the bottom-left corner
[in]w,hThe region size along the X and Y axes
[in]camA reference to a VR3Camera object (if 0 the current active camera is used instead)
[in]flagsA combination of one or more flags

void VR3Scene::BeginFBO ( VR3FBO fbo,
VR3Camera cam = 0,
int  flags = 0 
)

Starts the scene rendering, specifying the VR3FBO where to render the scene.

This function behaves like the Begin() function, but activating off-screen rendering on a specified VR3FBO. It is also possible to pass a VR3Camera object: it's projection and viewing parameters are used throughout the scene and is made the current active camera.

Parameters:
[in]fboThe target VR3FBO
[in]camA reference to a VR3Camera object (if 0 the current active camera is used instead)
[in]flagsA combination of one or more flags

void VR3Scene::BeginRel ( GLfloat  x,
GLfloat  y,
GLfloat  w,
GLfloat  h,
VR3Camera cam = 0,
int  flags = 0 
)

Starts the scene rendering, specifying an output relative screen region.

This function behaves like the Begin() function, but in addition specifies a subregion of the screen, expressed in normalized window coordinates (ranging in [0.0,1.0]), where the scene is drawn. Combined with other Begin()..End() blocks, it allows to realize split-screen or multi-screen applications. It is also possible to pass a VR3Camera object: it's projection and viewing parameters are used throughout the scene and is made the current active camera.

Parameters:
[in]x,yThe normalized window coordinates of the bottom-left corner
[in]w,hThe normalized region size along the X and Y axes
[in]camA reference to a VR3Camera object (if 0 the current active camera is used instead)
[in]flagsA combination of one or more flags

bool VR3Scene::CheckVFCulling (  ) [inline]

Checks whether view frustum culling is enabled or not.

This function is used at rendering time and is not to be called by the user. It simply checks if the view frustum culling feature is enabled.

Returns:
true if view frustum culling is enabled, false otherways

Definition at line 554 of file VR3Scene.h.

void VR3Scene::Disable ( int  feature,
int  optional_param = 0 
)

Disables a specific scene feature.

This function is used to disable a feature of the scene, currently the user may disable the following features specified through the feature parameter:

Parameters:
[in]featureThe desired feature
[in]optional_paramAn additional argument
void VR3Scene::Enable ( int  feature,
int  optional_param = 0 
)

Enables a specific scene feature.

This function is used to enable a feature of the scene, currently the user may enable the following features specified through the feature parameter:

Parameters:
[in]featureThe desired feature
[in]optional_paramAn additional argument
void VR3Scene::End (  )

Ends the scene rendering.

Indicates the end of the visual scene description.

void VR3Scene::EnvironmentMapping ( const char *  diff_file,
const char *  spec_file 
)

Enables the Image-Based Lighting mode specifying which cube maps to use.

This function is used to enable environment mapping for the current scene. Two cube map files name may be passed to specify the images to use to light the scene. When one of the 2 images assumes the value 0, the corresponding IBL component will be disabled (as if the image was completely black). If both file names are set to 0, environment mapping is disabled and ordinary lights are used again for rendering.

Parameters:
[in]diff_fileThe file containing the cube map to use for the diffuse light component (an HDR image is recommended)
[in]spec_fileThe file containing the cube map to use for the specular light component (an HDR image is recommended)
See also:
VR3TextureManager::LoadCubeMap()
const VR3SceneShaderParams* VR3Scene::FetchParameters (  ) [inline]

Scene properties discovery function.

This function is used during rendering to retrieve the values of some scene properties consumed by the shaders as uniform parameters.

Definition at line 586 of file VR3Scene.h.

GLint VR3Scene::GetActiveLights ( bool *  fa )

Gets an array of flags stating which lights are active.

When rendering, the number of active lights may be needed to pass the correct uniform values to the rendering shaders.

Parameters:
[out]faFlag array stating if some lights are active (true)
Returns:
The number of active lights
static VR3Scene* VR3Scene::GetActiveScene (  ) [inline, static]

Gets the current VR3Scene object.

This static method gets the currently active scene, notice that just one scene may be active at any given time.

Returns:
The active scene

Definition at line 245 of file VR3Scene.h.

VR3Texture* VR3Scene::GetBackground (  ) [inline]

Gets the current background.

This function may be used to get the background of the scene as a VR3Texture object to be used for shader-tuned rendering.

Returns:
The current background VR3Texture object

Definition at line 389 of file VR3Scene.h.

VR3Camera* VR3Scene::GetCurrentCamera (  ) [inline]

Gets the currently active camera.

Retrieves a reference to the currently active camera.

Returns:
The active camera

Definition at line 294 of file VR3Scene.h.

VR3Texture* VR3Scene::GetEnvMap ( GLint  map )

Gets one of the current environment maps as a VR3Texture object.

This function may be used to retrieve a reference to the VR3Texture object representing one of the environment maps in the scene (diffuse or specular). When a user has finished with the reference, the VR3Texture::Destroy() function should be called.

Parameters:
[in]mapThe map the user has requested, one of:

Returns:
The requested environment map
GLint VR3Scene::GetEnvMappingMode (  ) [inline]

Gets the current environment mapping mode.

This function is used to get the current environment mapping mode, and is called repeatedly while rendering (inline function for efficiency).

Definition at line 431 of file VR3Scene.h.

GLfloat VR3Scene::GetFrameRate (  ) [inline]

Gets the current frame rate.

The frame rate is computed once every 100 frames and this function can be used to extract the computed value. If multiple Begin()...End() blocks are used in a single frame, to obtain the correct framerate it is necessary to divide the value by the number of Begin()...End() blocks.

Returns:
The computed framerate

Definition at line 457 of file VR3Scene.h.

void VR3Scene::GetLightColor ( int  id,
int  color,
GLfloat *  c 
)

Gets the color of a light component.

Gets the color of a light with regard to a single color shading component (ambient, diffuse, or specular) depending on the color parameter. The color parameter may assume the values:

  • VR3LIGHT_AMBIENT
  • VR3LIGHT_DIFFUSE
  • VR3LIGHT_SPECULAR
Parameters:
[in]idThe light number
[in]colorThe desired color shading component
[out]cThe light color as a 4-components vector
void VR3Scene::GetLightPosition ( int  id,
GLfloat *  p 
)

Gets the position of a light.

Retrieves the position of a light in world coordinates (non homogeneous, 3-components vector).

Parameters:
[in]idThe light number
[out]pThe retrieved position
GLint VR3Scene::GetNumPolys (  ) [inline]

Gets the current number of polygons in meshes.

The number of polygons is computed for each Begin()...End() block, considering the objects that are drawn inside it. If multiple Begin()...End() blocks are used in a single frame, the result will oscillate during a the frame period, depending on what is drawn in the different Begin()...End() block. To obtain the total number of polygons in this case the user will have to add all results obtained after each block. If this function is called inside a Begin()...End() block the result will be the one from the previous block.

NOTE: The retrieved number of polygons only represents the number of polygons in the drawn VR3Objs in each frame. This value will not consider polygons used to render the background or skybox, polygons rendered in the shadow maps, polygons used to blur the shadow maps (4 per shadow map) and polygons used to render VR3Text objects (text strings).

Returns:
The last computed number of polygons

Definition at line 479 of file VR3Scene.h.

bool VR3Scene::HasBegun (  ) [inline]

Checks if the scene has begun.

Checks if the scene has begun (we are inside a Begin()..End() block).

Returns:
true if we are inside a Begin()..End() block, false otherways

Definition at line 497 of file VR3Scene.h.

bool VR3Scene::IsEnabled ( int  feature,
int  optional_param = 0 
)

Checks if a particular scene feature is active.

This function is used to check if a feature of the scene is active, currently the user may check the following features through the feature parameter:

Parameters:
[in]featureThe desired feature
[in]optional_paramAn additional argument
Returns:
true if the feature is enabled, false otherways
VR3Scene& VR3Scene::operator= ( const VR3Scene  ) [private]

Disable default assignment operator.

void VR3Scene::RealBegin ( GLsizei  width,
GLsizei  height,
VR3Camera cam,
int  flags 
) [private]

Starts the scene rendering.

This function is called by the public rendering begin functions, and is the one effectively taking care of initializing the rendering environment.

Parameters:
[in]width,heightThe resulting drawing subregion width and height (useful for projection matrix computation)
[in]camA reference to a VR3Camera object (if 0 the current active camera is used instead)
[in]flagsA combination of one or more flags

void VR3Scene::SetActiveCamera ( int  id )

Sets the currently active camera.

Sets the camera having the provided id as the active camera.

Parameters:
[in]idThe new active camera
void VR3Scene::SetBackground ( const char *  file_name,
bool  fl_skybox = false 
) [inline]

Loads a background from a file.

By default, a VR3Scene object has no background. The user may use this function to set a background for the scene. Two types of backgrounds are supported:

  • background image - A static image
  • skybox - An all-around background cube map that follows camera movements Passing a filename of 0 disables the scene background (default state).
Parameters:
[in]file_nameThe name of the background image containing file
[in]fl_skyboxFlag stating if the background is a skybox or a standard 2D texture image
See also:
VR3TextureManager::Load2D()
VR3TextureManager::LoadCubeMap()

Definition at line 380 of file VR3Scene.h.

void VR3Scene::SetClearColor ( GLfloat  r,
GLfloat  g,
GLfloat  b 
)

Sets the background cleaning color.

Specifies the color to use when cleaning the color buffer.

Parameters:
[in]r,g,bDesired color
void VR3Scene::SetClearColor ( const GLfloat *  color )

Sets the background cleaning color.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:
[in]colorDesired color vector (3 GLfloats)
void VR3Scene::SetFrameRate ( GLfloat  fps )

Sets the target frame rate.

Sets the target frame rate, i.e. the rate which the OnFrame() function is called at. This value determines the frequency of the graphical loop. The frame rate is meant as a target value, therefore it strongly depends on the used hardware and on the current software status. Impossible (<=0) or absurd (>200) requests will be ignored. If multiple Begin()...End() blocks are used in a single frame, we strongly discourage the usage of this function as the resulting framerate would result lower than the desired one.

Parameters:
[in]fpsThe desired frame rate
void VR3Scene::SetLightColor ( int  id,
int  color,
GLfloat  r,
GLfloat  g,
GLfloat  b 
)

Sets the color of a light component.

Sets the color of a light with regard to a single color shading component (ambient, diffuse, or specular) depending on the color parameter. The color parameter may assume the values:

  • VR3LIGHT_AMBIENT
  • VR3LIGHT_DIFFUSE
  • VR3LIGHT_SPECULAR
Parameters:
[in]idThe light number
[in]colorThe desired color shading component
[in]r,g,bThe desired color
void VR3Scene::SetLightPosition ( int  id,
GLfloat  x,
GLfloat  y,
GLfloat  z 
)

Sets the position of a light.

Sets the position of a specified light using world space coordinates.

Parameters:
[in]idThe light number
[in]x,y,zThe desired position
void VR3Scene::SetLightPosition ( int  id,
const GLfloat *  v 
)

Sets the position of a light.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:
[in]idThe light number
[in]vThe desired position
void VR3Scene::StoreUniforms ( GLsizei  width,
GLsizei  height 
)

Sets all uniform parameters consumed by the shaders once.

This function may be used to set once the scene uniform parameters consumed by shaders while rendering. It sets both the matrices parameters (depending on the camera and on the viewport dimensions) and the light parameters. Usually this function must not be used, it may be helpful if an application performs rendering using Begin()...End() where a particular type of uniform parameters set is never updated (using one of the VR3BEGFL_* flags).

Parameters:
[in]width,heightviewport dimensions used to compute the projection matrix
void VR3Scene::UpdateDrawRegion ( GLsizei  w,
GLsizei  h 
)

Updates the current global draw region size.

This function is used to refresh the OpenGL drawing area depending on the provided parameters, it modifies the region of the screen where the view frustum may be projected. The region may be separated in different subregions depending on the effect we want to obtain and should always match the OpenGL window area.

Parameters:
[in]w,hThe drawing region size
void VR3Scene::UpdateLightParams (  ) [private]

Updates the scene light uniform parameters to be used by the shaders.

This function is used to compute part of the shader parameters consumed by the shaders as uniforms during rendering. We prepare the properties of the currently active scene lights to be used by the shaders.

void VR3Scene::UpdateMatrices ( GLsizei  width,
GLsizei  height 
) [private]

Updates the projection and viewing matrix to be used by the shaders.

This function is used to compute part of the shader parameters consumed by the shaders as uniforms during rendering. We compute the projection matrix and update the viewing matrix depending on the active camera, width and height of the current viewport subarea. This function is called once for each Begin() to prepare the matrices for rendering.

Parameters:
[in]width,heightwidth and height of the current viewport subarea

Member Data Documentation

Scene background.

Definition at line 123 of file VR3Scene.h.

bool VR3Scene::m_beginendblock [private]

Flag stating if we are inside a Begin()..End() block.

Definition at line 98 of file VR3Scene.h.

VR3Camera VR3Scene::m_cameras[VR3SC_NUM_CAMERAS] [private]

Available cameras in the scene.

Definition at line 112 of file VR3Scene.h.

Currently active camera.

Definition at line 114 of file VR3Scene.h.

Diffuse lighting environment map (convolution of the above map)

Definition at line 150 of file VR3Scene.h.

GLint VR3Scene::m_env_mode [private]

Environment mapping mode.

  • VR3EM_NONE - Environment mapping disabled
    • VR3EM_DIFFUSE - Environment mapping performed only with diffuse component
    • VR3EM_SPECULAR - Environment mapping performed only with specular component
    • VR3EM_FULL - Full environemnt mapping (recommended when using IBL) This variable is stored separately from the effective maps to be recovered very quickly while rendering.

Definition at line 146 of file VR3Scene.h.

Specular lighting environment map.

Definition at line 148 of file VR3Scene.h.

bool VR3Scene::m_face_culling [private]

Backface culling enabled flag.

Backface culling is directly supported by the GL.

Definition at line 119 of file VR3Scene.h.

long VR3Scene::m_framecounter [private]

Frame counter for framerate computation.

Definition at line 104 of file VR3Scene.h.

GLfloat VR3Scene::m_framerate [private]

Continuously computed frame rate.

Definition at line 162 of file VR3Scene.h.

VR3Light VR3Scene::m_lights[VR3SC_NUM_LIGHTS] [private]

Available lights in the scene.

Definition at line 116 of file VR3Scene.h.

GLint VR3Scene::m_minframetime [private]

Minimum (target) frame time (in milliseconds)

Definition at line 160 of file VR3Scene.h.

int VR3Scene::m_polycounter [private]

Poligons counter.

Definition at line 106 of file VR3Scene.h.

int VR3Scene::m_polygons [private]

Continuously computed number of polygons.

Definition at line 125 of file VR3Scene.h.

Shader parameters values.

Definition at line 167 of file VR3Scene.h.

long VR3Scene::m_starttime [private]

Framerate computation start time (used every 100 frames)

Definition at line 102 of file VR3Scene.h.

long VR3Scene::m_time [private]

Last time value extracted (used for frame rate regulation)

Definition at line 100 of file VR3Scene.h.

GLsizei VR3Scene::m_totdrawregion[2] [private]

Global viewport size (window size)

Definition at line 158 of file VR3Scene.h.

bool VR3Scene::m_vf_culling [private]

View frustum culling enabled flag.

Definition at line 121 of file VR3Scene.h.

VR3Scene* VR3Scene::ms_activescene [static, private]

Pointer to the currently active VR3Scene object.

Definition at line 95 of file VR3Scene.h.


The documentation for this class was generated from the following file:
 All Classes Namespaces Files Functions Variables Typedefs Friends Defines