GLOW API version 1.0 reference

Back to Table of contents

class Glow

General information

type: class
inherits: (none)
module: glow

Glow encapsulates general routines for GLOW programs, including initialization, machine state, event delivery, setup of idle and timer tasks, and other functions. It also includes some useful constants. All methods of Glow are static; you cannot instantiate Glow.

All GLOW programs use Glow::Init() and Glow::MainLoop() to initialize and start the main event loop, respectively. Some programs may use the idle and timer functions. A few may use some of the advanced routines such as event simulation and resolution of GLUT window and menu IDs.

Constants

Event masks
Tells a window which event types to report. Used during creation of a window or subwindow. These constants are defined as an enumeration of type Glow::EventMask and should be or'ed together.

enum Glow::EventMask noEvents

Report no events

enum Glow::EventMask keyboardEvents

Report keypress events

enum Glow::EventMask mouseEvents

Report mouse button events

enum Glow::EventMask dragEvents

Report mouse motion while dragging events

enum Glow::EventMask motionEvents

Report mouse motion while button is up events

enum Glow::EventMask visibilityEvents

Report visible and invisible events

enum Glow::EventMask focusEvents

Report got focus and lost focus events

enum Glow::EventMask menuEvents

Report menu up and menu down events

enum Glow::EventMask allEvents

Report all events

Button ID
Specifies which mouse button is affected. Used for various things such as attaching menus. Also passed back during mouse event callbacks. Defined as an enumeration of type Glow::MouseButton.

enum Glow::MouseButton leftButton

Left mouse button. Corresponds to GLUT_LEFT_BUTTON.

enum Glow::MouseButton middleButton

Middle mouse button. Corresponds to GLUT_MIDDLE_BUTTON.

enum Glow::MouseButton rightButton

Right mouse button. Corresponds to GLUT_RIGHT_BUTTON.

Buffer type
Specifies the type of frame buffer requested. Used in constructing a window or subwindow. These values should be or'ed together. Defined as an enumeration of type Glow::BufferType.

enum Glow::BufferType noBuffer

No buffers.

enum Glow::BufferType rgbBuffer

RGB color buffer. Corresponds to GLUT_RGB.

enum Glow::BufferType alphaBuffer

Alpha buffer. Corresponds to GLUT_ALPHA.

enum Glow::BufferType rgbaBuffer

RGBA color buffer. Corresponds to rgbBuffer | alphaBuffer. Note that this is different from GLUT_RGBA, which is the same as GLUT_RGB.

enum Glow::BufferType stencilBuffer

Stencil buffer. Corresponds to GLUT_STENCIL.

enum Glow::BufferType depthBuffer

Depth (Z) buffer. Corresponds to GLUT_DEPTH.

enum Glow::BufferType accumBuffer

Accumulation buffer. Corresponds to GLUT_ACCUM.

enum Glow::BufferType doubleBuffer

Double buffer. Corresponds to GLUT_DOUBLE.

enum Glow::BufferType stereoBuffer

Stereo buffer. Corresponds to GLUT_STEREO. Note that this buffer type is not commonly supported. Call IsBufferTypeSupported() to check before attempting to create a window with a stereo buffer.

enum Glow::BufferType multisampleBuffer

Multisampling buffer. Corresponds to GLUT_MULTISAMPLE. Note that this buffer type is not commonly supported. Call IsBufferTypeSupported() to check before attempting to create a window with a multisampling buffer.

Keyboard modifiers
Describes modifier keys associated with an event. Passed back during an event callback. Defined as an enumeration of type Glow::Modifiers.

enum Glow::Modifiers noModifier

No modifiers down.

enum Glow::Modifiers shiftModifier

Shift key down. Corresponds to GLUT_ACTIVE_SHIFT.

enum Glow::Modifiers ctrlModifier

Ctrl key down. Corresponds to GLUT_ACTIVE_CTRL.

enum Glow::Modifiers altModifier

Alt key down. Corresponds to GLUT_ACTIVE_ALT.

Keyboard constants
Specifies the key pressed in a keyboard event. Keys with associated ASCII codes are represented by their corresponding ASCII code. Constants for keys without an associated ASCII code, as well as a few common but not well-known ASCII key codes, are also provided below. Defined as an enumeration of type Glow::KeyCode. The special constant specialKeyOffset serves to offset the non-ASCII constants from their corresponding GLUT constant. e.g. f1key == GLUT_KEY_F1 + specialKeyConstant.

enum Glow::KeyCode backspaceKey
enum Glow::KeyCode tabKey
enum Glow::KeyCode enterKey
enum Glow::KeyCode escapeKey
enum Glow::KeyCode deleteKey

enum Glow::KeyCode specialKeyOffset
enum Glow::KeyCode f1Key
enum Glow::KeyCode f2Key
enum Glow::KeyCode f3Key
enum Glow::KeyCode f4Key
enum Glow::KeyCode f5Key
enum Glow::KeyCode f6Key
enum Glow::KeyCode f7Key
enum Glow::KeyCode f8Key
enum Glow::KeyCode f9Key
enum Glow::KeyCode f10Key
enum Glow::KeyCode f11Key
enum Glow::KeyCode f12Key
enum Glow::KeyCode leftArrowKey
enum Glow::KeyCode upArrowKey
enum Glow::KeyCode rightArrowKey
enum Glow::KeyCode downArrowKey
enum Glow::KeyCode pageUpKey
enum Glow::KeyCode pageDownKey
enum Glow::KeyCode homeKey
enum Glow::KeyCode endKey
enum Glow::KeyCode insertKey

Static methods

General methods

static void Init(int& argc, char** argv)

Initializes GLOW. Should be called once at the beginning of the program. Pass argc and argv to it.

static void MainLoop(void)

Starts the GLOW main loop. Should be called once after all program initialization is complete. The call never returns normally.

static double Version(void)

Returns the version of GLOW currently in use. This value is also defined by the constant GLOW_VERSION. The value is of the form a.bbccdd where a is the major release number, b is the major revision number, c is the minor revision number and d is the prerelease number (99 for final). Hence, version 1.3.11pre4 would show up as 1.031104. This is a non-inline method, so you can test that the headers match up with the library at runtime by comparing GLOW_VERSION with the value returned by Version().

static int APIVersion(void)

Returns the version of the GLOW API currently in use. This value is also defined by the constant GLOW_APIVERSION. For the GLOW 1.0 release, the API version is 1. This is a non-inline method, so you can test that the headers match up with the library at runtime by comparing GLOW_APIVERSION with the value returned by APIVersion().

Managing idle tasks
Idle tasks are descendents of GlowIdleReceiver. Tasks that are registered will receive a GlowIdleMessage periodically whenever the program is idle.

static void RegisterIdle(GlowIdleReceiver* idle)

Registers the given idle task with the GLOW system. Has no effect if the receiver is already registered.

static void UnregisterIdle(GlowIdleReceiver* idle)

Unregisters the given idle receiver. Has no effect if the reciver is not already registered.

static void UnregisterAllIdle(void)

Unregisters all idle receivers.

static int NumRegisteredIdle(void)

Returns the number of registered idle receivers.

static bool IsRegisteredIdle(GlowIdleReceiver* idle)

Returns true if and only if the given idle receiver is registered.

Managing timer tasks
Timer tasks are descendents of GlowTimerReceiver. Registered tasks will receive a GlowTimerMessage soon after the given number of milliseconds have elapsed. There is no guarantee about the exact amount of time, but it will be at least msecs milliseconds, and as soon afterwards as the system can schedule.

static int RegisterTimer(unsigned int msecs, GlowTimerReceiver* timer)

Registers the given timer receiver with the GLOW system. Returns a unique ID to identify this particular timer request. The ID will be included in the message sent. It may also be used to unregister the timer task or to check on its status.

static void UnregisterTimer(int id)

Unregisters the timer task specified by the given unique ID. If the task has not yet been executed, it will be cancelled.

static bool IsTimerPending(int id)

Returns true if and only if the given id refers to a timer task that has been registered and has not yet been executed.

Managing event filters
Event filters can be set up to pre-filter events before they are delivered. They can modify the parameters of the event, or even handle the event themselves and consume the event so it is not passed on to the receiving object.

static void RegisterFilter(GlowKeyboardFilter* filter)

Adds the given keyboard event filter to the list of filters run for keyboard events. Has no effect if the filter is already registered.

static void RegisterFilter(GlowMouseFilter* filter)

Adds the given mouse event filter to the list of filters run for mouse up and mouse down events. Has no effect if the filter is already registered.

static void UnregisterFilter(GlowKeyboardFilter* filter)

Removes the given keyboard event filter from the list of filters run for keyboard events. Has no effect if the filter is not registered.

static void UnregisterFilter(GlowMouseFilter* filter)

Removes the given mouse event filter from the list of filters run for mouse up and mouse down events. Has no effect if the filter is not registered.

static void UnregisterAllKeyboardFilters(void)

Unregisters all keyboard event filters, but doesn't modify the mouse event filter list.

static void UnregisterAllMouseFilters(void)

Unregisters all mouse event filters, but doesn't modify the keyboard event filter list.

static unsigned int NumRegisteredKeyboardFilters(void)

Returns the number of registered keyboard event filters.

static unsigned int NumRegisteredMouseFilters(void)

Returns the number of registered mouse event filters.

static bool IsFilterRegistered(GlowKeyboardFilter* filter)

Reports whether the given keyboard event filter is registered.

static bool IsFilterRegistered(GlowMouseFilter* filter)

Reports whether the given mouse event filter is registered.

Managing modal windows
GLOW keeps a stack of modal toplevel windows. If the stack is non-empty, the window occupying the top of the stack is made to "grab" events. That is, all other windows are temporarily deactivated, normally preventing events from being delivered to the deactivated windows. This is useful for implementing alerts and other dialog boxes that require immediate attention. Because modal windows are stored in a stack, you may nest modal windows.

static void PushModalWindow(GlowWindow* window)

Pushes the given window onto the modal window stack, deactivating all other windows.

static void PopModalWindow(void)

Pops the topmost window off the modal window stack. If this results in the stack being empty, GLOW reactivates other toplevel windows. Otherwise, the next window in the stack is made the focused window. Has no effect if there are no modal windows.

static int NumModalWindows(void)

Returns the size of the modal window stack. This is 0 if no window is modal.

static GlowWindow* TopModalWindow(void)

Returns the top of the modal window stack (i.e. the currently modal window), or 0 if there is no modal window.

Toplevel window management
GLOW provides the option of exiting the program automatically when the last toplevel window is deleted. The auto-quit feature is disabled by default, but may be enabled or manipulated using these routines.

static int NumToplevelWindows(void)

Returns the number of toplevel GLOW window objects in existence. This includes windows that are hidden or iconified.

static bool IsAutoQuitting(void)

Returns true if auto-quitting is active.

static void SetAutoQuitting(bool autoQuitting = true)

Activates or deactivates the auto-quitting feature.

Miscellaneous state

static bool IsMenuDown(void)

Returns true if and only if a menu is currently down. It is not safe to manipulate menu data structures in this state.

static int GetMilliseconds(void)

Returns the number of milliseconds since GLOW was initialized.

static bool IsExtensionSupported(const char* extensionName)

Determines whether the OpenGL extension with the specified name is supported by the current implementation. This function requires a window to be present; it will throw an assertion otherwise.

static bool IsBufferTypeSupported(Glow::BufferType type)

Determines whether the given frame buffer type is supported. If it isn't, you should not attempt to create a window with that buffer type.

static int NumMouseButtons(void)

Returns the number of mouse buttons supported by the implementation. If two buttons are supported, they will be Glow::leftButton and Glow::rightButton. If only one button is supported, it will be Glow::leftButton.

GLUT integration
These routines provide services to assist you with using GLUT and GLOW in the same program. GLOW provides replacement functions for glutIdleFunc() and glutMenuStatusFunc(), and an implementation of glutPostWindowRedisplay() that functions under the GLUT 3 APIs. You can also resolve GLUT window and menu IDs into GlowSubwindow* or GlowMenu* pointers, respectively.

static void SetIdleFunc(void (*func)())

Performs the same function as GLUT's function glutIdleFunc(). If you are integrating GLOW and GLUT code, or if you otherwise want to use a callback-based API for your idle function, you must use this function instead of glutIdleFunc().

static void SetMenuStatusFunc(void (*func)(int status, int x, int y))

Performs the same function as GLUT's function glutMenuStatusFunc(). If you are integrating GLOW and GLUT code and want to register a menu status function, you must use this function instead of glutMenuStatusFunc().

static void RefreshGlutWindow(int windowid)

Refreshes a GLUT window with the given ID. Equivalent to the GLUT 4 function ::glutPostWindowRedisplay(), but also works under the GLUT 3 API.

static GlowSubwindow* ResolveWindow(int windowNum)

Returns a pointer to the GlowSubwindow associated with the given id, or 0 if there is no such GLOW window.

static GlowMenu* ResolveMenu(int menuNum)

Returns a pointer to the GlowMenu associated with the given id, or 0 if there is no such GLOW menu.

Delivering events
These advanced routines allow you to simulate events in GlowSubwindows. They deliver the appropriate event messages to the objects, causing the event handler to be called. The event handler is called regardless of the state of the subwindow's event mask. Normally, you should not need to simulate events in this manner.

static void DeliverKeyboardEvt(GlowSubwindow* receiver, Glow::KeyCode key, int x, int y, Glow::Modifiers modifiers)

Delivers a keypress event to the specified subwindow.

static void DeliverMouseDownEvt(GlowSubwindow* receiver, Glow::MouseButton button, int x, int y, Glow::Modifiers modifiers)

Delivers a mouse button down event to the specified subwindow.

static void DeliverMouseUpEvt(GlowSubwindow* receiver, Glow::MouseButton button, int x, int y, Glow::Modifiers modifiers)

Delivers a mouse button up event to the specified subwindow.

static void DeliverMouseDragEvt(GlowSubwindow* receiver, int x, int y)

Delivers a mouse button drag event to the specified subwindow.

static void DeliverMouseMotionEvt(GlowSubwindow* receiver, int x, int y)

Delivers a mouse motion event to the specified subwindow.

static void DeliverMouseEnterEvt(GlowSubwindow* receiver)

Delivers a cursor entered event to the specified subwindow.

static void DeliverMouseExitEvt(GlowSubwindow* receiver)

Delivers a cursor exited event to the specified subwindow.

Drawing methods
These advanced routines provide miscellaneous drawing services.

static void SwapBuffers()

Causes the front and back buffers for the current drawing context to be swapped. Equivalent to calling ::glutSwapBuffers(). Normally, you do not need to call this, because GLOW will normally swap buffers automatically.

Back to Table of contents