Main Page | Class List | Class Members

osgchips Documentation

1.0.0

Introduction

osgchips provides a 3D representation of casino chips. Casino chips are flat cylinders, usually made of clay, that represent money when playing skill games such as poker. The color of the chip is associated to a value, which may also be written in the center of the chip. They can be used in any kind of game where representing wagers is relevant. The caller controls the size of the chip stacks, their placements, their color and transparency.

A single osgchips::Stacks object (derived from osg::Geode) can contain multiple osgchips::Stack objects (derived from osg::Geometry). Picking is enabled on the bounding box of the osgchips::Stacks object and not on a per osgchips::Stack basis to save CPU time. The various type of chips are stored in the osgchips::ChipBank singleton.

Usage

The API documentation is complete, meaning that if a method is not documented it is not part of the API. Undocumented functions are public so that a developper familiar with the internals can make use of them.

The osgchips::Stacks and osgchips::Stack derive publicly from OpenSceneGraph classes (osg::Geode and osg::Geometry respectively) so that specific application needs may be addressed. For instance, the application may want to set state attributes on a osgchips::Stack using the osg::StateSet pointer returned by getStateSet().

The API is designed for simplicity, as demonstrated in the osgchips.cpp example.

  osgchips::Stacks* stacks = dynamic_cast<osgchips::Stacks*>(osgDB::readNodeFile("default.osgchips"));

Example

The osgchips example reads the default.osgchips file and displays the osgchips::Stacks object created from it.

osgchips-screenshot.png

XML configuration element

The osgchips XML element provides a mean to fill the osgchips::ChipBank singleton that describes each type of chip. It can also be used to creat an osgchips::Stacks object as follows:

   
#include <osgDB/ReadFile>
osgchips::Stacks* stacks = dynamic_cast<osgchips::Stacks*>(osgDB::readNodeFile("default.osgchips"));

Each element of the configuration file and its use are described in the comments of the sample file shown below. This file is available from the source distribution in data/default.osgchips or in /usr/share/osgchips/default.osgchips if installed on GNU/Linux. It is used by the osgchips example.

<?xml version='1.0' encoding='iso-8859-1' ?> <!-- -*- nxml -*- -->

<!--

osgchips configuration file. The order of the elements is important: material, chip and stacks.

-->

<!--

osgchips element

Defines chips that are stored in the osgchips::ChipBank singleton and/or create a osgchips::Stacks
object.

mesh = mesh file that can be read by osgDB::readNodeFile to create a osg::Geode (mandatory)
-->

<osgchips xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	  xsi:noNamespaceSchemaLocation="http://download.gna.org/osgchips/osgchips.xsd"
	  mesh="chip.osg" >

  <!--
      material element

      Defines a material that can be referenced in the material attribute of the chip element.
      name = symbolic name of the material (mandatory)
      red = [0-255] integer (optional, default 0)
      green = [0-255] integer (optional, default 0)
      blue = [0-255] integer (optional, default 0)
      alpha = [0-1] float (optional, default 1)

      Example: <material name="colored" red="100" green="255" blue="255" alpha="1.0" />

  -->
  <material name="transparent" red="255" green="100" blue="255" alpha="0.5" />
  <material name="colored" red="100" green="255" blue="255" alpha="1.0" />
  
  <!--
      chip element
      
      Defines a chip that can be referenced in the chip attribute of the stack element.
      The material and/or the texture attributes must be specified for the stacks to
      be visible. If two chips have the same value, only the last one will be returned
      by the osgchips::ChipBank::getChip(unsigned int value) method. The same apply for
      two chips with the same name and osgchips::ChipBank::getChip(const std::string& name).

      name = symbolic name of the chip (mandatory)
      value = [1-N] integer numerical value of the chip (mandatory)
      texture = URI of the image used as a texture for the mesh /osgchips@mesh. (optional, no default)
		See the README or osgchips HTML documentation for more information.
      material = reference to the material element defined earlier in this file (optional, no default)
      
      Example: <chip name="1" texture="white-1.png" value="1" />

  -->
  <chip name="1" texture="white-1.png" value="1" />
  <chip name="2" texture="yellow-2.png" value="2" />
  <chip name="5" texture="red-5.png" value="5" />
  <chip name="10" texture="blue-10.png" value="10" />
  <chip name="20" texture="grey-20.png" value="20" />
  <chip name="25" texture="green-25.png" value="25" />
  <chip name="50" texture="orange-50.png" value="50" />
  <chip name="100" texture="black-100.png" value="100" />
  <chip name="250" texture="pink-250.png" value="250" />
  <chip name="500" texture="purple-500.png" value="500" />
  <chip name="1000" texture="burgundy-1000.png" value="1000" />
  <chip name="2000" texture="lightblue-2000.png" value="2000" />
  <chip name="5000" texture="brown-5000.png" value="5000" />

  <chip name="transparent-100" material="transparent" value="100" />
  <chip name="tinted-250" material="transparent" texture="pink-250.png" value="250" />
  <chip name="colored-100" material="colored" texture="black-100.png" value="100" />

  <!-- 
       stacks element 
       
       Defines an osgchip::Stacks object
  -->
  <stacks>
    <!--
	stack element
	
	Defines a chip stack and its position. The chip mesh is translated so that its
	bottom center is on the specified position.
	
	chip = reference to the chip element defined in the osg::ChipBank singleton, either
	       because it was read in this file or because it was previously read from another
	       file.
	count = number of chips in the stack (optional, default 1)
	x = [0-N] float, position on the x axis (optional, default 0)
	y = [0-N] float, position on the y axis (optional, default 0)
	z = [0-N] float, position on the z axis (optional, default 0)
    -->
    <stack chip="50" count="5" x="0" y="0" z="0" />
    <stack chip="25" count="0" x="20" y="0" z="0" />
    <stack chip="100" count="2"  x="0" y="0" z="10" />
    <stack chip="transparent-100" count="20"  x="0" y="0" z="-10" />
    <stack chip="100" count="5"  x="0" y="0" z="-15" />
    <stack chip="transparent-100" count="20"  x="0" y="0" z="-20" />
    <stack chip="tinted-250" count="10"  x="10" y="0" z="0" />
    <stack chip="colored-100" count="13" x="-10" y="0" z="0" />

    <stack chip="1" count="5" x="0" y="0" z="-50" />
    <stack chip="2" count="5" x="5" y="0" z="-50" />
    <stack chip="5" count="5" x="10" y="0" z="-50" />
    <stack chip="10" count="5" x="15" y="0" z="-50" />
    <stack chip="20" count="5" x="20" y="0" z="-50" />
    <stack chip="25" count="5" x="25" y="0" z="-50" />
    <stack chip="50" count="5" x="30" y="0" z="-50" />
    <stack chip="100" count="5" x="35" y="0" z="-50" />
    <stack chip="250" count="5" x="40" y="0" z="-50" />
    <stack chip="500" count="5" x="45" y="0" z="-50" />
    <stack chip="1000" count="5" x="50" y="0" z="-50" />
    <stack chip="2000" count="5" x="55" y="0" z="-50" />
    <stack chip="5000" count="5" x="60" y="0" z="-50" />
  </stacks>
  
</osgchips>

Error handling policy

Errors are signaled with the return value of the methods. No exception is thrown. Warning or informative messages may be issued using the osg::Notify facility.

Debug

osgchips has partial support for writing to OpenSceneGraph ascii format (.osg). It is convenient to get a complete description of the OpenSceneGraph objects created by the osgchips library. The output generated cannot be read back.

Resources usage

Memory

Assuming that a single osgchips::ChipBank instance exists in the application, no osgchips::ChipBank::Chip is duplicated. When two osgchips::Stack instances use the same osgchips::ChipBank::Chip, they do not duplicate it.

The osgchips::ChipBank instance stores a single copy of the vertexes, normals, texture coordinates and primitive sets (osg::PrimitiveSet) that define the cylinder for a chip stack. The vertexes and texture coordinates are duplicated for each osg::Stack instance (for resizing purposes) but the normals and primitive sets are shared.

CPU <=> GPU

The mesh is small (less than 100 faces) therefore display lists and VBO are disabled because it will not be faster if they are used. The overhead of OpenGL calls to enable the VBO and the display list is roughly equivalent to the overhead of OpenGL calls that would be made if they are not used. In addition, not using them saves memory on the 3D card.

Using osgchips in your code

osgchips is provided as an installable package that can easily be integrated to a third party software using the autotools and pkg-config facilities.

The source code itself is designed to be self contained so that copying the .cpp and .h files in another application is an alternative that does not require any modification.

Coordinate system

The coordinate system used is the same as OpenGL (Y pointing up).

Thread safety

osgchips is thread safe. For applications that do not need thread safety, the osgchips::ChipBank singleton makes the API simpler. If thread safety is needed, the application must not rely on the osgchips::ChipBank singleton.

3D assets

Each chip relies on a mesh and (optionally) a texture for rendering. The mesh is provided in the data/chip.osg OpenSceneGraph ascii format. The corresponding Blender file is in data/chip.blend and uses the data/white-1.png texture.

Mesh

Provided in data/chip.osg. The mesh can be stored in any OpenSceneGraph supported format as long as osgDB::readNodeFile returns an osg::Geode object. Vertexes, normal, texture coordinates and primitives (think osg::PrimitiveSet) will be used. No other information will be used. The mesh must have its bottom center located at 0, 0, 0 with up on Y.

blender-mesh.png

Texture

Provided in data/white-1.png.

white-1.png
The mapping of the image on the mesh (blender screenshot)
blender-texture.png

In order to be mapped properly, the texture image must have the following properties:

blender-constraints.png

The file data/chips.xcf contains the gimp source from which the chip images for all chips can be generated.

Dependencies

osgchips depends on OpenSceneGraph (http://openscenegraph.org/).

osgchips depends on libxml2 (http://xmlsoft.org/).

Legalese

Copyright

Copyright (C) 2004 Mekensleep

Mekensleep
24 rue vieille du temple
75004 Paris
      licensing@mekensleep.com

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

Authors


Generated on Wed Dec 15 14:45:58 2004 for osgchips by  doxygen 1.3.9.1