G3D is a commercial-grade 3D Engine available as Open Source (BSD License). It is used in games, tech demos, research papers, military simulators, and university courses. It provides a set of routines and structures so common that they are needed in almost every graphics program. It makes low-level libraries like OpenGL and sockets easier to use without limiting functionality or performance. G3D gives you a rock-solid, highly optimized base from which to build your application.

The documentation assumes that you are familiar with the basics of 3D graphics programming. If you are new to 3D graphics, then we recommend The Graphics Codex, Graphics Codex Projects, and . They are closely integrated with G3D and will teach you how to use the engine effectively.

G3D contains only lightweight scene graphs and GUI routines. Because of this, you have much more flexibility in how you structure your programs. The tradeoff is that you have to know more about 3D programming. We recommend using wxWidgets or another GUI library with G3D if your project has extensive UI needs beyond the controls provided by G3D::GuiPane.

The library also provides lower-level interfaces that programmers who are already working with OpenGL and existing code may prefer. See the Notes for Expert Users at the end of this chapter for more information.

Documentation and Support

This guide gives a brief introduction to help you decide if G3D is right for your project and introduce you to the major features. The individual entry points are extensively documented and can be accessed through the links at the top of this page. The source code for the entire library is available (http://casual-effects.com/g3d) and can often help resolve ambiguities.

Post questions and feedback on the User Forum (http://groups.google.com/group/g3d-users/topics) and consider subscribing to it to receive all posts via e-mail. Don't be afraid to post if you are a new or inexperienced user– the User Forum is our primary support path.

G3D provides several demos with source that show different ways of structuring your 3D program and how to use some of the most popular features in samples.

The official support team and community respond to most user posts within hours and patches for critical user-discovered bugs are given top priority.
The latest version library is always available on the homepage, http://casual-effects.com/g3d.

Platform and Functionality

G3D allows you to write code once that will compile and run on Windows, Linux, and OS X without ifdefs or modifications.
It supports all OpenGL implementations, from software rasterization under Mesa to the latest GeForce and Radeon hardware accelerator cards.

G3D is built on OpenGL because it is platform independent and allows access to newer features than DirectX. Many top games (including Doom 3) are written with OpenGL. There are advantages to both APIs, but in the end they are equivalent except for the platform issue. You can implement any effect from any game in G3D. Unlike higher level engines G3D does not restrict access to low-level features– every graphics card function in OpenGL is exposed under G3D, even if it isn't wrapped by a higher level API. This means you can always drop down to raw OpenGL calls if needed.

Design Philosophy

Our philosophy is simple. The library should have the following properties:

Easy to use!
Only contains code needed for every 3D project.
It is hard to write bugs...
and easy to find them.
You can use pieces of the library without the whole.
Defaults are safe and fast.
The license encourages both commercial and non-commercial use.
It is easy to build the library and link against it.
Provides access to popular data formats.
The same source code runs on all operating systems and graphics cards.
Manages resources for the user.

Data Formats

G3D supports images in PNG, TGA, BMP, JPG, PCX, PPM, PGM, PBM, DDS, and ICO format through the G3D::Texture, G3D::Image3, G3D::GImage classes. G3D has loaders for the BSP, PLY2, IFS, OFF, 3DS, OBJ, and MD2 mesh formats. G3D uses its own font format (FNT) to avoid legal issues with TrueType. Over 30 popular fonts are provided in this format and the code contains a routine to help you make more from your TrueType fonts. G3D::GuiTheme skins are in open source SKN format, which is implicitly documented by the G3D::GuiTheme class source code and will be explicitly documented in a future release (the format is currently under development).

Download the G3D data module for over 10 GB of models and other 3D data supported by G3D.

G3D is supported by donations from users (http://sourceforge.net/project/project_donations.php?group_id=76879), and by hardware, software, and technical support from Autodesk, NVIDIA, and AMD.

Working With Other Libraries

G3D is compatible with most other libraries.
Although G3D provides its own native window management, you can use the G3D::OSWindow API to replace that with GUI libraries, likw wxWindows and Qt.

It is possible to use DirectX instead of OpenGL. The easiest way is to link against G3D-base.lib only and use DirectX calls instead of the GLG3D equivalents. A more full-featured solution is to replace the G3D-gfx.lib implementation with DirectX versions and rebuild the entire library.
To avoid memory leaks, ensure that all libraries you use have been compiled against the same version of the C++ standard library. G3D expects to be compiled with run-time type checking (RTTI), C++ exceptions, and a multithreaded, dynamically linked runtime.

G3D uses ffmpeg, zlib, libpng, libzip, and libjpeg, which are distributed as part of G3D (as headers and a windows .libs). These are automatically built into G3D and your program–you don't have to do anything special to use them.

On Linux and FreeBSD, G3D::SDLWindow uses SDL. SDL is not included with the G3D installation and must be downloaded separately from http://libsdl.org if it is not installed on your machine already.

In addition to those mentioned above, you may be interested in using the following libraries to complement G3D:

Image Magick's Magick Wand (http://www.imagemagick.org/)
Free Type2 (http://freetype.sourceforge.net/index2.html)
STLport (http://www.stlport.org/download.html)

Release Schedule

G3D has a stable, backwards compatible API. Most changes between versions add functionality and fix bugs. Point releases are backwards compatible to the last major release, except where critical bugs necessitate small API changes. Point releases occur about once every two months and are announced on the User Forum.

Major releases may break source compatibility to fix critical bugs, match the changing hardware standards, and streamline the API. Incompatible changes are marked in the Change Log and an upgrade path is recommended. Major releases occur about once a year and are announced well in advance. Migrating code across major releases generally takes a few hours of work for a 100,000 line program. We try to design changes so they will trigger compiler errors for older code instead of failing silently.

Beta releases occur between point releases to allow users to access new functionality and provide feedback. Beta releases are frequently Windows-only and are neither supported nor guaranteed to be stable. Any APIs in a Beta release may change without notice.

Beta and Deprecated APIs

Even in official releases, some parts of G3D are marked as Beta in the documentation. These are previews of new APIs that are still under construction but are stable enough to use. They will likely change in small ways before becoming official APIs– use at your own risk.

Deprecated APIs have been replaced by some newer functionality but are supported and guaranteed to be present until the next major release, at which point they will be removed. Avoid writing new code to deprecated APIs and consider migrating existing code away from them.

Notes for Expert Users

G3D is designed so that you can use as much or as little as you want. You are welcome to rip out the source code for a single class like G3D::Texture and use it standalone in your project, link against the library and use our main G3D::RenderDevice class, or let G3D::GApp provide the entire structure for your program. For example, you might want to use the G3D::Vector3 and other low-level classes but provide your own rendering state abstraction, or use DirectX instead of OpenGL.

Most G3D programs need not access OpenGL directly. However, you can always execute OpenGL functions directly and mix them with RenderDevice calls. To ensure that the G3D::RenderDevice is properly synchronized, wrap this code in G3D::RenderDevice::beginOpenGL, G3D::RenderDevice::endOpenGL. Most classes, like Texture, expose the relevant OpenGL handles so you can work with them directly as needed.

The routines are packaged as two static libraries, G3D and GLG3D, so that you can use the low-level vector math without bringing in any of the OpenGL code.

You may find it easier (particularly on Windows) to debug code if you build G3D on your own machine so that you can step into the G3D routines and set breakpoints and watch variables. On Windows you should change the Debug Info level to Program Database from Line Numbers Only.