[ Requirements & Installation ] [ Conceptual Overview ] [ The Part Editor ] [ The Geometry Editor ] [ Importing 3ds models ] [ Examples ] [ OpenGL Subsystem ] [ Inside the Part Editor ] [ Input Device Details ] [ Inside CoolPool ] [ Inside Lunar Lander ] [ Deploying Applications ] [ Resources and Links ]

Appendix A. The OpenGL Subsystem

CcOpenglLibrary and CcOpengluLibrary

ST3D uses the Microsoft Windows implementation of the OpenGL API to render graphic primitives such as lines, polygons and points. ExternalLibrary subclass CcOpenglLibrary wraps functions exported by Opengl32.dll. System global variable "Opengl" holds the solitaire instance of CcOpenglLibrary. Application software should only use methods categorized as "OpenGL public". Methods in category "OpenGL private", prefixed with the letters "gl", should not be used outside of CcOpenglLibrary.

ExternalLibrary subclass CcOpengluLibrary wraps the OpenGL utility functions of Openglu32.dll. The CcOpengluLibrary solitaire is held by system global Openglu. It’s normally unnecessary to reference Openglu in application code since CcOpenglLibrary provides convenience methods for accessing most CcOpengluLibrary services.

Instance methods have been added to class GDILibrary to allow access to several OpenGL-related functions provided by Win32 (these functions are also known as the "OpenGL window system bindings"). Again, it is normally not necessary to reference the solitaire for GDILibrary since CcOpenglLibrary provides convenience methods for accessing these services.

Most methods on CcOpenglLibrary have a corresponding entry point in Opengl32.dll. An indication of the argument types expected by a method is provided by the argument names (e.g., "intMode") or by the method comment. Method comments do not, in general, provide a comprehensive description of the method’s function or the allowed values for the arguments. For this level of detail, the developer should consult the appropriate section of the OpenGL Programmer’s Guide/Reference or the online OpenGL documentation included with various software development toolkits (e.g., Visual C++).

Detailed API specifications for Opengl32.dll and Openglu32.dll are also available online at http://trant.sgi.com/opengl/docs/man_pages/hardcopy/GL/html/gl/ and http://trant.sgi.com/opengl/docs/man_pages/hardcopy/GL/html/glu/, respectively.

Many of the constants referenced in the OpenGL API specification are available in pool dictionary CcOpenGLConstants.  CcPoolConstantsDictionary>>importHeaderString: can be used to import additional constants from a C header file.

When creating a Smalltalk wrapper (external call method) for a given OpenGL function, use the following mapping between OpenGL argument types and Dolphin external call argument types:

GLenum -> dword

GLint -> sdword

GLsizei -> sdword

GLuint -> dword

More information on the OpenGL API can be found in the "OpenGL Programming Guide" (See "Other Sources of Information").

 CcOpenglView and CcOpenglPresenter

CcOpenglView is a subclass of View that supports OpenGL rendering. CcOpenglView provides behavior for initializing the resources required by OpenGL such as rendering contexts and device contexts (see CcOpenglView>>onCreated:). CcOpenglView has a single subclass: CcOpenglSingleBufferView.

CcOpenglSingleBufferView uses a single display buffer. CcOpenglView uses two buffers. Using two buffers is commonly referred to as "double buffering". Double buffering should always be used for applications involving animation. Attempting animation in single buffer mode will often produce a flickering effect since the contents of the buffer are visible during all drawing operations and when the buffer is cleared between frames. In double buffered mode, only one of the buffers is visible at a time. The currently visible buffer is referred to as the "front buffer" and the off screen buffer is referred to as the "back buffer". During the animation process, OpenGL drawing commands are directed to the hidden back buffer. Once a scene is fully rendered onto the back buffer, the front and back buffers are "swapped" so that the back buffer becomes visible (almost instantaneously) and the front buffer is hidden. The key is that drawing and clearing operations never occur on a buffer while it is visible.

Instances of CcOpenglView and CcOpenglSingleBufferView are normally associated with CcOpenglPresenters. CcOpenglPresenter owns two resources: "DefaultView" (an instance of CcOpenglView) and "Single buffer" (an instance of CcOpenglSingleBufferView).

CcRenderingContext

CcRenderingContext represents an OpenGL rendering context. A rendering context is analogous to a Windows GDI device context in that it maintains state information such as the current color and current line width. Each instance of CcOpenglView has its own rendering context.

At any given point in time, the system has a single rendering context that is considered "current". The current context is the implicit target for almost all OpenGL commands (i.e., the rendering context is not included as an argument for most OpenGL commands). When a view requires repainting, one of the first tasks is to make that view’s rendering context current.

ST3D manages a "default" rendering context (CcRenderingContext(class)>>defaultContext) that’s initialized within a hidden view prior to the creation of any other contexts. The default context allows the sharing of display lists and textures between multiple contexts and views.