OpenCSG The CSG rendering library News    Introduction    Benefits    Prerequisites    Usage    Download    Applications    License    FAQ

OpenCSG version 1.0.2 released (04.12.2004)

Introduction

OpenCSG is a library that does image-based CSG rendering using OpenGL. OpenCSG is written in C++ and supports most modern graphics hardware using Microsoft Windows or the Linux operating system. OpenCSG-1.0.2 is the current version.

What is CSG, anyway? CSG is short for Constructive Solid Geometry and denotes an approach to model complex 3D-shapes using simpler ones. I.e., two shapes can be combined by taking the union of them, by intersecting them, or by subtracting one shape of the other. The most basic shapes, which are not result of such a CSG operation, are called primitives. Primitives must be solid, i.e., they must have a clearly defined interior and exterior. By construction, a CSG shape is also solid then.

Image-based CSG rendering (also z-buffer CSG rendering) is a term that denotes algorithms for rendering CSG shapes without an explicit calculation of the geometric boundary of a CSG shape. Such algorithms use frame-buffer settings of the graphics hardware, e.g., the depth and stencil buffer, to compose CSG shapes. OpenCSG implements a variety of those algorithms, namely the Goldfeather algorithm and the SCS algorithm, both of them in several variants.

Benefits

CSG is often used as fundamental modeling technique in CAD/CAM applications. Here, image-based CSG rendering is the key to interactively manipulate CSG shapes. Since OpenCSG renders even complex CSG shapes fast, it can be advantageously used in such applications.

Raytracers such as PovRay have used CSG for shape modeling since long ago. Interactive modeling toolkits for such raytracers normally just ignore CSG commands, though. OpenCSG represents a valuable addition for such applications.

Overall, up to the present CSG rendering has been hardly used in interactive applications, since the necessary algorithms are complicated and error-prone. We hope that by providing a free library that is easy to use, fast, and versatile, CSG rendering can be made more mainstream than it currently is.

Prerequisites

The OpenCSG library requires graphics hardware that supports the PBuffer of OpenGL. It is advantegeous if the related Render-to-Texture facility is also supported. Actually, OpenCSG uses the RenderTexture class as PBuffer library.

PBuffers have been widely supported since some time ago. NVidia supports them since the Riva TNT, and ATI at least since the Radeon series. Graphics hardware from other hardware vendors, however, likely do not support PBuffers. Therefore, if you have obscure graphics hardware, you are probably out of luck and you cannot run programs using OpenCSG. With Linux, you have probably the option to use supporting OpenGL software rendering and PBuffers at the same time.

For OpenGL-Extension checking, the OpenGL Extension Wrangler Library GLEW is used.

OpenCSG is written in C++, uses namespaces and requires the STL. I do not expect major compiler incompatibilities under Windows. Workspaces for with MSVC6, VC2003 .net and Dev-C++ 5 beta are provided. Under Linux, you must use gcc-3.x.y. gcc-2.95.x will not work, since this compiler does not come with a std::map implementation, which is required internally.

To run OpenCSG well, you should have graphics hardware with lots of fill rate. NVidia graphics hardware since GeForce and ATI Radeon qualify. The OpenCSG::OcclusionQuery option obviously requires occlusion queries, which are available since Radeon 9x00 (x>=5) and GeForce3 (beware that the GeForce4MX counts as GeForce2!).

OpenCSG has been sucessfully run on Intel and AMD hardware using GeForceFX 5600, GeForce3, GeForce4MX, Radeon 9700, and TNT2 graphcs hardware (on the latter, it crawls ...). On a Radeon 9000, there are currently rendering errors in all but the standard Goldfeather rendering path. I am investigating this further, but the problem is possibly a driver issue.

Usage

The interface of OpenCSG is very easy to use. There is only a single abstract class called OpenCSG::Primitive. A Primitive object has an attribute Operation that denotes whether the primitive is intersected or subtracted. To use OpenCSG, create a derived concrete primitive class by implementing the render() method.

To actually do the CSG rendering, there is the function OpenCSG::render() that takes a std::vector<Primitive*> as argument. The render function evaluates the CSG expression given by the array of primitives and initializes the z-buffer with the proper values for the CSG expression. The color buffer remains unchanged, so afterwards, you must shade the primitives in the array using a GL_EQUAL depth function.

Note that the render function does not evaluate a generic CSG tree that also would contain unions of CSG shapes. It has been shown that a generic CSG tree can be converted into an equivalent set of CSG expressions that the render function can handle. OpenCSG does not contain the functionality for this conversion since, after all, it is a rendering library.

Here is the complete interface of OpenCSG:

namespace OpenCSG {

  enum Operation { Intersection, Subtraction };

  class Primitive {
  public:
   Primitive(Operation, unsigned int convexity);
   virtual ~Primitive();

   void setOperation(Operation);
   Operation getOperation() const;

   void setConvexity(unsigned int);
   unsigned int getConvexity() const;

   void setBoundingBox(float minx, float miny, float minz,
     float maxx, float maxy, float maxz);
   void getBoundingBox(float& minx, float& miny, float& minz,
     float& maxx, float& maxy, float& maxz) const;

   virtual void render() = 0;
  };

  enum Algorithm { Automatic, Goldfeather, SCS };
  enum DepthComplexityAlgorithm { NoDepthComplexitySampling,
    OcclusionQuery, DepthComplexitySampling };

  void render(const std::vector<Primitive*>& primitives,
    Algorithm = Automatic,
    DepthComplexityAlgorithm = NoDepthComplexitySampling);
}


The convexity of a primitive is the maximum number of front (or back) faces of the primitive at a single position. For example, the convexity of a sphere is one and the convexity of a torus is two. Actually the convexity attribute is currently only used in the standard Goldfeather algorithm. For this algorithm, a convexity too low may result in rendering errors, a convexity too high will reduce rendering performance. The other Goldfeather variants render primitives of any convexity correctly without analyzing the convexity attribute. The SCS algorithms, on the other hand, can only handle primitives that have a convexity of one, else they produce rendering errors. Hence, SCS algorithms do not check this attribute.

The bounding box of the primitive can be provided using normal device coordinates, i.e., after transforming the primitive with modelview and projection transformation. It is not necessary to set the bounding box, but it allows for various performance optimizations.

The abstract render method of the primitive is implemented in a derived class. Your implementation must not alter the modelview or projection matrix (use glPushMatrix / glPopMatrix if in doubt). Also you must not change the primary color in your implementation, since OpenCSG uses it internally (in all rendering algorithms). For best performance, you should only transmit vertex positions; no normals, texture coordinates, or whatever else.

The render function performs, as said above, z-shading of a CSG expression. The content of the stencil buffer is destroyed when handling concave primitives or when using the DepthComplexitySampling strategy.

The Algorithm parameter specifies the method used for CSG rendering. Besides Goldfeather and SCS, you can also choose Automatic: This setting chooses the Goldfeather algorithm if the primitive array contains concave primitives, else it chooses SCS. The automatic setting also sets the DepthComplexityAlgorithm (NoDepthComplexitySampling for arrays with few primitives, else OcclusionQuery or at the last resort DepthComplexitySampling).

Aforesaid means that it is, currently, not possible to do CSG rendering of concave primitives and preserving the stencil buffer. I am looking for ways to change this situation (The ARB_buffer_region extension appears to be a possible way for this).

If the Automatic setting is not used, the DepthComplexityAlgorithm parameter specifies the strategy for profiting from depth complexity.

• NoDepthComplexitySampling: Does not employ the depth complexity. This essentially makes the algorithm O(n²), but with low constant costs.
• DepthComplexitySampling: Calculates the depth complexity k using the stencil buffer. This makes the algorithm O(n*k), but with high constant costs. In case of the Goldfeather algorithm, the literature denotes this as layered Goldfeather algorithm.
• OcclusionQuery: Uses occlusion queries to profit implicitly from depth complexity without calculating it. This is especially useful for the SCS algorithm where this strategy is applied at shape level, resulting in a O(n*k') algorithm (where k' <= k), without significant constant overhead. This strategy requires hardware occlusion queries, i.E., the OpenGL extension GL_ARB_occlusion_query or GL_NV_occlusion_query.

Download

Download OpenCSG-1.0.2.zip. The archive contains all required helper libraries, i.e., also RenderTexture and GLEW. It comes with makefiles for Linux and with project files for MSVC6, VS2003, and Dev-C++ 5.

The older versions
   OpenCSG-1.0.1.zip,
   OpenCSG-1.0.0.zip,
   OpenCSG-0.9.2,
   OpenCSG-0.9.1 and
   OpenCSG-0.9
are still available for download.

Applications

Currently, I know of the following applications making use of OpenCSG:

	Ayam is a 3D modelling environment for the RenderMan interface, running on Unix, Win32, and Mac OS X. Since version 1.8, Ayam provides the plugin aycsg for real-time CSG preview of complex CSG hierarchies using OpenCSG as rendering library.
	koraX's CSG Editor. This editor for MS Windows allows to compose textured CSG shapes from a set of predefined primitives. The application contains a very good online help that depicts nicely what CSG is about, and that furthermore contains some tutorial how to create 1) a graphical widget and 2) a pipe.

License

OpenCSG is copyrighted by the Hasso-Plattner-Institute at the University of Potsdam (HPI), Germany, and by Florian Kirsch.

You can license OpenCSG by terms of the GNU GPL, Version 2. This means that you may release applications or libraries that use (parts of) OpenCSG (a) only if you release the complete source code of your application or library and (b) only if you release it under the GPL license.

If you do not want to release your source code unter terms of the GPL, you can't use and link against OpenCSG by licensing it unter GPL. In this case, e.g., if you want to use OpenCSG in a proprietary application or library, you can always ask for a separate license and use it for development and production purposes.

According to the GPL, you are free to modify and redistribute OpenCSG under terms of the GPL. We welcome contribution of your modifications to OpenCSG, however to let us integrate your modifications into OpenCSG, you must assign the copyright of the modifications to the HPI, Florian Kirsch. In other words, modifications from you that you would like to be integrated into OpenCSG should not hinder us to distribute OpenCSG under other, non-free licenses.

Note that OpenCSG comes with code that is not under copyright of the HPI or Florian Kirsch. These are GLEW and RenderTexture. These libraries are licensed under the terms of their respective authors.

FAQ

1. Can I render a shape with different colors? The documentation says I must not change the primary color in the function of my class for primitives, since OpenCSG uses the color for internal purposes.

   You can shade your shapes with whatever color you want. While your primitive objects for use in OpenCSG must not use the primary color, after calculating z-values with OpenCSG you are free to render the same geometry with primary colors.

2. What are the dependencies of the example program?

   The OpenCSG example requires GLUT. This library is likely pre-installed with your favorite linux installation. Visual Studio users can install GLUT for Windows. Dev-C++ users can install the precompiled GLUT for Mingw32.