Image Component Library (ICL)
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines
Classes | Public Types | Public Member Functions | Static Public Member Functions | Public Attributes | Protected Member Functions | Protected Attributes | Static Private Member Functions | Friends
icl::geom::Scene Class Reference

Scene Implementation that is used to handle a list of objects and cameras. More...

#include <Scene.h>

Inheritance diagram for icl::geom::Scene:
icl::utils::Lockable icl::utils::Configurable

List of all members.

Classes

struct  PBufferIndex

Public Types

enum  DepthBufferMode { RawDepth01, DistToCamPlane, DistToCamCenter }

Public Member Functions

 Scene ()
 Base constructor (creates an empty scene)
 ~Scene ()
 Destructor.
 Scene (const Scene &scene)
 Explicitly implemented deep copy (performs complete deep copy of all cameras and objects)
Sceneoperator= (const Scene &scene)
 Assignment operator (complete deep copy)
void addCamera (const Camera &cam, float visSize=1.0)
 Adds a new Camera to the scene.
void removeCamera (int index)
 removed the camera at given index
CameragetCamera (int camIndex=0)
 returns a reference to the i-th camera
const CameragetCamera (int camIndex=0) const
 returns the i-th scene camera
int getCameraCount () const
 returns the count of contained cameras
std::vector< Camera * > getAllCameras (int firstIndex=0, int num=-1)
 returns a vector with pointers to all cameras in given range
void addObject (SceneObject *object, bool passOwnerShip=false)
 adds a new top-level object to the Scene instance
void removeObject (int idx)
 removed object at given index
void removeObject (const SceneObject *obj)
 removes given top-level object from scene (not recursive)
void removeObjects (int startIndex, int endIndex=-1)
 removed object at given indices
int getObjectCount () const
 returns the number of top-level objects
SceneObjectgetObject (int index) throw (utils::ICLException)
 returns contained object at given index
const SceneObjectgetObject (int index) const throw (utils::ICLException)
 returns contained object at given index (const)
SceneObjectgetObject (const std::vector< int > recursiveIndices) throw (utils::ICLException)
 returns a child that is deeper in the scene graph
SceneObjectgetObject (const std::vector< int > recursiveIndices) const throw (utils::ICLException)
 returns a child that is deeper in the scene graph (const)
std::vector< int > findPath (const SceneObject *o) const throw (utils::ICLException)
 finds the recursive indices for a given object.
void clear (bool camerasToo=false)
 deletes and removes all objects, handlers and callbacks
qt::MouseHandlergetMouseHandler (int camIndex=0)
 returns a mouse handler that adapts the scene's camera using mouse-interaction
void setMouseHandler (SceneMouseHandler *sceneMouseHandler, int camIndex=0)
 registeres a custom SceneMouseHandler for given camera index
qt::ICLDrawWidget3D::GLCallbackgetGLCallback (int camIndex)
 returns a callback that is used to render the scene into a GL-context
const core::Img8urender (int camIndx, const core::ImgBase *background=0, core::Img32f *depthBuffer=0, DepthBufferMode mode=DistToCamCenter) const throw (utils::ICLException)
 renders the current scene using an instance of glx pbuffer
void freeAllPBuffers ()
 frees all pbuffers allocated before
void freePBuffer (const utils::Size &size)
 frees the pbffer associated with given size (if there is one)
void createShadowFBO (unsigned int size=512, unsigned int lights=8) const
 creates the FBO and Texture
void freeShadowFBO () const
 frees all resources that are needed by the shadowmap
void setDrawCamerasEnabled (bool enabled)
 sets wheter cameras are also visualized in scenes.
bool getDrawCamerasEnabled () const
 returns whether cameras are visualized
void setDrawLightsEnabled (bool enabled, float lightSize=1)
 sets wheter lights are also visualized in scenes.
bool getDrawLightsEnabled () const
 returns whether lights are visualized
void setDrawCoordinateFrameEnabled (bool enabled, float size=120)
 sets wheter a coordinate frame is automatically inserted into the scene
bool getDrawCoordinateFrameEnabled () const
 returns wheter a coordinate frame is automatically shown in the scene
void setDrawObjectFramesEnabled (bool enabled, float size)
 sets whether all object frames are visualized
bool getDrawObjectFramesEnabled () const
 returns whether object frames are visualized
SceneLightgetLight (int index) throw (utils::ICLException)
 returns a reference to a light with given index
const SceneLightgetLight (int index) const throw (utils::ICLException)
 returns a const reference to a light with given index
void setLightingEnabled (bool flag)
 sets whether OpenGL's lighting is globally activated
void setGlobalAmbientLight (const GeomColor &color)
 this can be used to change OpenGL's global ambient light color
Hit findObject (int camIndex, int xScreen, int yScreen)
 picks the closest contained scene-object clicked at given ScreenPosition
Hit findObject (const ViewRay &v)
 picks the first object that is hit by the given viewray
std::vector< HitfindObjects (const ViewRay &v)
 retunrs all objects intersected by the given viewray
std::vector< HitfindObjects (int camIndex, int xScreen, int ySceen)
 retunrs all objects on that are intersected by the defined cameras viewray through given x and y
void setBounds (float minX, float maxX=0, float minY=0, float mayY=0, float minZ=0, float maxZ=0)
 sets the expected bounds of contained objects
void setBackgroundColor (const GeomColor &color)
 sets the scene's background color (alpha is not used)
GeomColor getBackgroundColor () const
 returns the current background colo

Static Public Member Functions

static void enableSharedOffscreenRendering ()
 This function must be called when rendering a Scene from two different GLContexts.
static void disableSharedOffscreenRendering ()
 re-enables the dirty flag in the GLImg class

Public Attributes

GLuint shadowTexture
 GLuint pointing to the shadowmap texture.
GLuint shadowFBO
 GLuint pointing to the shadowmap FBO.
unsigned int shadowResolution
 resolution at which the shadowmap is rendered (in this implementation shadowmaps are always square)
icl::qt::GLFragmentShaderm_perPixelShader
 the shader used for per pixel lighting and shadowmaps

Protected Member Functions

void createDisplayList (SceneObject *o) const
 creates a displaylist for the given object
void freeDisplayList (SceneObject *o) const
 frees the display list, that is associated with an object
void renderScene (int camIndex, qt::ICLDrawWidget3D *widget=0) const
 internally used rendering method
void renderShadow (const unsigned int light, unsigned int size=512) const
 renders the shadowmap
void recompilePerPixelShader () const
 recompiles the shader for the current light configuration
void renderSceneObjectRecursiveShadow (SceneObject *o) const
void renderSceneObjectRecursive (SceneObject *o) const
 internally used rendering method for recursive rendering of the scene graph
void renderSceneObjectRecursive (const std::vector< geom::Mat > *project2shadow, SceneObject *o) const
 internally used rendering method for recursive rendering of the scene graph
void renderObjectFramesRecursive (SceneObject *o, SceneObject *cs) const
 recursively renders object frames for all scene objects
float getMaxSceneDim () const
 internally used utility method that computes the extend of the Scene content
void extendMaxSceneDimRecursive (float &minX, float &maxX, float &minY, float &maxY, float &minZ, float &maxZ, SceneObject *o) const
 recursive utility method

Protected Attributes

std::vector< Cameram_cameras
 internal list of cameras
std::vector< utils::SmartPtr
< SceneObject > > 
m_objects
 internal list of top-level objects
std::vector< utils::SmartPtr
< SceneObject > > 
m_cameraObjects
 internal list of top-level camera objects used for camera visualization
std::vector< utils::SmartPtr
< SceneMouseHandler > > 
m_mouseHandlers
 internally used list of mouse handlers
std::vector< utils::SmartPtr
< GLCallback > > 
m_glCallbacks
 internally used list of callbacks
std::map< PBufferIndex, PBuffer * > m_pbuffers
 intenal list of of offscreen rendering buffers
utils::SmartPtr< SceneObjectm_coordinateFrameObject
 internally used scene object
utils::SmartPtr< SceneObjectm_objectFrameObject
 also internally used object frame object
utils::SmartPtr< SceneLightm_lights [8]
 internal list of lights
int m_previousLightState [8]
 previous lightstate
utils::SmartArray
< utils::Range32f > 
m_bounds
 optionally given bounds of the scene
math::FixedColVector< int, 4 > m_globalAmbientLight
 global ambient light
GeomColor m_backgroundColor
 current scene background color

Static Private Member Functions

static void freeDisplayList (void *handle)
 called from the SceneObject class

Friends

class SceneObject
 make SceneObject friend of Scene

Detailed Description

Scene Implementation that is used to handle a list of objects and cameras.

The scene combines visual objects (icl::SceneObject) which define nodes of a scene graph and cameras. You can use ICL's camera calibration tool icl-cam-calib (and icl-cam-calib-2) to calibrate cameras in your scene. Later, you can define a scene (including SceneObject-instances) and use the calibrated camera to draw the Scene as an image overlay.

The following example demonstrates how to use the Scene class. The example can also be found at ICLGeom/examples/geom-demo-simple.cpp. A more complex demo that also uses the Scene's scene graph can be found at ICLGeom/examples/scene-graph-demo.cpp

  #include <ICLQt/Common.h>
  #include <ICLGeom/Geom.h>
  #include <ICLUtils/FPSLimiter.h>

  // global data
  icl::qt::GUI gui;
  Scene scene;

  void init(){
    // create graphical user interface with a scene's viewport set of size 640x480
    gui << Draw3D(utils::Size(640,480)).minSize(16,12).handle("draw").label("scene view")
        << FSlider(0.5,20,3).out("f").handle("focal").label("focal length").maxSize(100,3);
    gui.show();

    // create camera and add to scene instance
    Camera cam(Vec(0,0,-10), // position
               Vec(0,0,1),   // view-direction
               Vec(1,0,0));   // up-direction
    scene.addCamera(cam);


    if(pa("-o")){ // either load an .obj file
      scene.addObject(new SceneObject(*pa("-o")));
    }else{ // or create a simple cube
      float data[] = {0,0,0,7,3,2};
      scene.addObject(new SceneObject("cuboid",data));
    }

    // link the scene's first camera with mouse gestures in the draw-GUI-component
    gui["draw"].install(scene.getMouseHandler(0));
  }


  void run(){
    DrawHandle3D draw = gui["draw"]; // get the draw-GUI compoment
    scene.getCamera(0).setFocalLength(gui["f"]); // update the camera's focal length

    // now simply copy and past this block ...
    draw->link(scene.getGLCallback(0)); // render the whole scene
    draw.render();   // post an update-event (don't use draw->render() !!)

    static FPSLimiter limiter(25);
    limiter.wait();
  }


  int main(int n, char**ppc){
    return ICLApplication(n,ppc,"-obj|-o(.obj-filename)",init,run).exec();
  }

Member Enumeration Documentation

Enumerator:
RawDepth01 

raw core::depth buffer in range [0,1]

DistToCamPlane 

core::depth buffer values define distance to the camera's z=0 plane

DistToCamCenter 

core::depth buffer values define distanct to the camera center


Constructor & Destructor Documentation

Base constructor (creates an empty scene)

Destructor.

icl::geom::Scene::Scene ( const Scene scene)

Explicitly implemented deep copy (performs complete deep copy of all cameras and objects)


Member Function Documentation

void icl::geom::Scene::addCamera ( const Camera cam,
float  visSize = 1.0 
)

Adds a new Camera to the scene.

Parameters:
camwhich is copied into the scene
visSizethis parameter determines the size of the 3D visualized cameras in the scene. If visSize is 1.0, The camera coordinate system is visualized with size 50x50x50. Actually, the visSize you need depends on the unit you use for your scene in your application. The default visSize is quite appropriate if you work with mm. If you e.g. use cm instead, visSize should be set to 0.1.
void icl::geom::Scene::addObject ( SceneObject object,
bool  passOwnerShip = false 
)

adds a new top-level object to the Scene instance

By default, the object's memory is managed externally. If you want to pass the ownership to the Scene instance, you have to set passOwnerShip to true.

void icl::geom::Scene::clear ( bool  camerasToo = false)

deletes and removes all objects, handlers and callbacks

If camerasToo is set to true, also all cameras are removed

void icl::geom::Scene::createDisplayList ( SceneObject o) const [protected]

creates a displaylist for the given object

void icl::geom::Scene::createShadowFBO ( unsigned int  size = 512,
unsigned int  lights = 8 
) const

creates the FBO and Texture

re-enables the dirty flag in the GLImg class

This function must be called when rendering a Scene from two different GLContexts.

This does in particular happen, when a single Scene is rendered on a widget and into an offsceen buffer. In this case, stored texture-ID's are only valid in a single thread, which is why, textures need to be updated everytime, they are drawn.

Possible Fix in the Future

We plan to fix this issue with a more elaborated texture ID handling in the ICLQt GLImg class.

void icl::geom::Scene::extendMaxSceneDimRecursive ( float &  minX,
float &  maxX,
float &  minY,
float &  maxY,
float &  minZ,
float &  maxZ,
SceneObject o 
) const [protected]

recursive utility method

Hit icl::geom::Scene::findObject ( int  camIndex,
int  xScreen,
int  yScreen 
) [inline]

picks the closest contained scene-object clicked at given ScreenPosition

returns 0 if no object was hit, if contactPos is not 0, the 3D-contact position is stored there.

picks the first object that is hit by the given viewray

The first object that is returned has the smallest distance to the given viewRay's offset. If contactPos is not 0, the contact point is stored there.

std::vector<Hit> icl::geom::Scene::findObjects ( const ViewRay v)

retunrs all objects intersected by the given viewray

std::vector<Hit> icl::geom::Scene::findObjects ( int  camIndex,
int  xScreen,
int  ySceen 
) [inline]

retunrs all objects on that are intersected by the defined cameras viewray through given x and y

std::vector<int> icl::geom::Scene::findPath ( const SceneObject o) const throw (utils::ICLException)

finds the recursive indices for a given object.

If no exceptions are thrown, getObject(findPath(o)) is always o. throws ans exception if the given object cannot be found.

frees all pbuffers allocated before

void icl::geom::Scene::freeDisplayList ( SceneObject o) const [protected]

frees the display list, that is associated with an object

static void icl::geom::Scene::freeDisplayList ( void *  handle) [static, private]

called from the SceneObject class

frees the pbffer associated with given size (if there is one)

frees all resources that are needed by the shadowmap

std::vector<Camera*> icl::geom::Scene::getAllCameras ( int  firstIndex = 0,
int  num = -1 
)

returns a vector with pointers to all cameras in given range

Please note, that the results become invalid if addCamera() or removeCamera() was called. If 'num' selects more cameras than possible, is it just increased appropriately automatically.

returns the current background colo

Camera& icl::geom::Scene::getCamera ( int  camIndex = 0)

returns a reference to the i-th camera

This can also be used to set the camera or to set's some of it's properties:

          // set a totally new camera
          scene.getCamera(0) = Camera(...);
        
          // update the focal length only
          scene.getCamera(0).setFocalLength(77);
const Camera& icl::geom::Scene::getCamera ( int  camIndex = 0) const

returns the i-th scene camera

int icl::geom::Scene::getCameraCount ( ) const [inline]

returns the count of contained cameras

returns whether cameras are visualized

returns wheter a coordinate frame is automatically shown in the scene

returns whether lights are visualized

returns whether object frames are visualized

returns a callback that is used to render the scene into a GL-context

please see ICLQt::ICLDrawWidget3D::callback

returns a reference to a light with given index

The returned reference cam be used to set lighting parameters. Since OpenGL does only support 8 lights, allowed indices are 0-7. If another index is passed, an exception is thrown.

const SceneLight& icl::geom::Scene::getLight ( int  index) const throw (utils::ICLException)

returns a const reference to a light with given index

Since OpenGL does only support 8 lights, allowed indices are 0-7. If another index is passed, an exception is thrown.

float icl::geom::Scene::getMaxSceneDim ( ) const [protected]

internally used utility method that computes the extend of the Scene content

The extend is used when scene mouse handlers are created. Here, it will e.g. compute a usefull step when moving forward or strafing.

returns a mouse handler that adapts the scene's camera using mouse-interaction

returns contained object at given index

If the index is not valid, an exception is thrown

const SceneObject* icl::geom::Scene::getObject ( int  index) const throw (utils::ICLException)

returns contained object at given index (const)

If the index is not valid, an exception is thrown

SceneObject* icl::geom::Scene::getObject ( const std::vector< int >  recursiveIndices) throw (utils::ICLException)

returns a child that is deeper in the scene graph

e.g. if recursiveIndices is [1,2,3], then first, the Scene's object at index 1 is used. Then this objects child at index 2. And finally that objects child at index 3 is returned. An exception is thrown if one of the indices is wrong.

SceneObject* icl::geom::Scene::getObject ( const std::vector< int >  recursiveIndices) const throw (utils::ICLException)

returns a child that is deeper in the scene graph (const)

e.g. if recursiveIndices is [1,2,3], then first, the Scene's object at index 1 is used. Then this objects child at index 2. And finally that objects child at index 3 is returned. An exception is thrown if one of the indices is wrong.

int icl::geom::Scene::getObjectCount ( ) const [inline]

returns the number of top-level objects

Scene& icl::geom::Scene::operator= ( const Scene scene)

Assignment operator (complete deep copy)

void icl::geom::Scene::recompilePerPixelShader ( ) const [protected]

recompiles the shader for the current light configuration

void icl::geom::Scene::removeCamera ( int  index)

removed the camera at given index

void icl::geom::Scene::removeObject ( int  idx)

removed object at given index

The object is deleted if it's ownwership was passed

removes given top-level object from scene (not recursive)

The object is deleted if it's ownwership was passed

void icl::geom::Scene::removeObjects ( int  startIndex,
int  endIndex = -1 
)

removed object at given indices

The object's are deleted if their ownwership was passed

const core::Img8u& icl::geom::Scene::render ( int  camIndx,
const core::ImgBase background = 0,
core::Img32f depthBuffer = 0,
DepthBufferMode  mode = DistToCamCenter 
) const throw (utils::ICLException)

renders the current scene using an instance of glx pbuffer

This method is currently only supported on linux systems, since the used pbuffer (OpenGL offscreen framebuffer object)

The method trys to create a default r8 g8 b8 pbuffer with 24Bit depthbuffer. If this is not supported, an at least 4 4 4 16 context is tryed to be created. If this does also fail, an exception will be thrown.

Shared Offsceen Rendering

When a single scene is used for both on- and offscreen rendering, an internal optimation needs to be deactivated by calling Scene::enableSharedOffscreenRendering.

Please note: The rendering pbuffer is allocated on the graphics card. Per definition, pbuffers are located in the screenbuffer memory segment which might be much smaller than the actual memory of your graphics card. Therefore, it is strongly recommended to free all pbuffers when they are no longer used. The pbuffer that is created to render the image in this method is stored internally and it will remain allocated for later use. If you need to render images of different sizes (the output image is rendered to the image size that the camera at given index has), you should free the pbuffers from time to time using Scene::freeAllPBuffers and Scene::freePBuffer(const utils::Size&).

If a non-null depthBuffer parameter is provided, it is filled with data from the scene core::depth buffer usually, the raw core::depth buffer does not provide useful information for further processing. In OpenGL, the standard core::depth buffer values are highly non-linearily distributed within the near and far clipping plane. If the core::depth buffer mode is not RawDepth01, this is compensated and the core::depth buffer is filled with (metric) core::depth values that denote either a pixel's distance to the z=0 plane in camera space or the distance to the camera center. For correcting the linearized core::depth buffer values that are computed for the DistToCamPlane mode, a set of correction coefficients has to be computed, which entails creation of all camera viewrays. This can last about a second in the first call. In later calls, the values are just re-used.

void icl::geom::Scene::renderObjectFramesRecursive ( SceneObject o,
SceneObject cs 
) const [protected]

recursively renders object frames for all scene objects

void icl::geom::Scene::renderScene ( int  camIndex,
qt::ICLDrawWidget3D widget = 0 
) const [protected]

internally used rendering method

void icl::geom::Scene::renderSceneObjectRecursive ( SceneObject o) const [inline, protected]

internally used rendering method for recursive rendering of the scene graph

void icl::geom::Scene::renderSceneObjectRecursive ( const std::vector< geom::Mat > *  project2shadow,
SceneObject o 
) const [protected]

internally used rendering method for recursive rendering of the scene graph

void icl::geom::Scene::renderShadow ( const unsigned int  light,
unsigned int  size = 512 
) const [protected]

renders the shadowmap

sets the scene's background color (alpha is not used)

channel ranges are assumed to be in [0,255]. The default background color is black

void icl::geom::Scene::setBounds ( float  minX,
float  maxX = 0,
float  minY = 0,
float  mayY = 0,
float  minZ = 0,
float  maxZ = 0 
)

sets the expected bounds of contained objects

The set information is used when a mouse-handler is created, in order to estimate appropriate step sizes. If the scene bounds were not explicitly, the scene tries to infer this information from the contained objects
Each [min-max] range where min=max, is automatically set to [minX,maxX]. If additionally, minX is equal to maxX, max is is set to -minX. If the resulting x-range has still zero length, the bounds are deleted internally

sets wheter cameras are also visualized in scenes.

This means, that you will be able to see e.g. camera 1 in the view of camera 0

void icl::geom::Scene::setDrawCoordinateFrameEnabled ( bool  enabled,
float  size = 120 
)

sets wheter a coordinate frame is automatically inserted into the scene

void icl::geom::Scene::setDrawLightsEnabled ( bool  enabled,
float  lightSize = 1 
)

sets wheter lights are also visualized in scenes.

void icl::geom::Scene::setDrawObjectFramesEnabled ( bool  enabled,
float  size 
)

sets whether all object frames are visualized

this can be used to change OpenGL's global ambient light color

by default, we use a very weak white ambient background light of [255,255,255,20]. The color values are given in ranges [0,255]

sets whether OpenGL's lighting is globally activated

by default, lighting is activated

void icl::geom::Scene::setMouseHandler ( SceneMouseHandler sceneMouseHandler,
int  camIndex = 0 
)

registeres a custom SceneMouseHandler for given camera index


Friends And Related Function Documentation

friend class SceneObject [friend]

make SceneObject friend of Scene


Member Data Documentation

current scene background color

utils::SmartArray<utils::Range32f> icl::geom::Scene::m_bounds [protected]

optionally given bounds of the scene

internal list of top-level camera objects used for camera visualization

std::vector<Camera> icl::geom::Scene::m_cameras [protected]

internal list of cameras

internally used scene object

std::vector<utils::SmartPtr<GLCallback> > icl::geom::Scene::m_glCallbacks [protected]

internally used list of callbacks

global ambient light

internal list of lights

internally used list of mouse handlers

also internally used object frame object

internal list of top-level objects

std::map<PBufferIndex,PBuffer*> icl::geom::Scene::m_pbuffers [mutable, protected]

intenal list of of offscreen rendering buffers

the shader used for per pixel lighting and shadowmaps

int icl::geom::Scene::m_previousLightState[8] [mutable, protected]

previous lightstate

GLuint icl::geom::Scene::shadowFBO [mutable]

GLuint pointing to the shadowmap FBO.

unsigned int icl::geom::Scene::shadowResolution [mutable]

resolution at which the shadowmap is rendered (in this implementation shadowmaps are always square)

GLuint pointing to the shadowmap texture.


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