about news documentation discuss download add-ons credits

Version 1.0 Documentation

Win32 Adapter Specific Notes

1. Standard Types
2. Compile Configuration
3. Cpw State Context
4. Initializing and Exiting Cpw
5. Cpw Errors
6. Global User Context
7. Print Output Handler
8. Desktop Video Settings
9. Main Execution Loop
10. Window Display Surface
11. Default Window Characteristics
12. Creating A Normal Window
13. Creating A Fullscreen Window
14. Window User Contexts
15. Windows Management
16. Window Event Callbacks
17. Window Specific Event Callbacks
18. Window Cursors
19. Mouse and Keyboard Polling
20. Timers
21. Event Stack
22. Popup and Titlebar Menus
23. Loading Images
24. Saving Images
25. Taking Screenshots
26. TrueType Fonts
27. Joysticks
28. 2D and 3D Primitive Rendering
29. OpenGL Extension Information
30. Performance Timing
31. Simple Frame Counter
32. Retrieving Constants





Cpw Standardized Types

The Cpw library adheres to a set of cross-platform standardized types and values. By including cpw.h in your project you have use of these in your application. ( You do not have to use them however.)

Cpw Type Constants:

Cpw type -> compatible standard type
------------------------------------
bool     -> boolean value
pVoid    -> void * pointer
pChar    -> char * pointer
uint_8   -> 8-bit unsigned integer
uint_16  -> 16-bit unsigned integer
uint_32  -> 32-bit unsigned integer
int_16   -> 16-bit integer
int_32   -> 32-bit integer
int_64   -> 64-bit integer
float_32 -> 32-bit floating point
float_64 -> 64 bit double or float
long_32  -> 32-bit long

Cpw value constant
------------------
true 
false
null 




Compile Configuration

A central compile configuration file exists which controls a number features and limits within Cpw when compiling the library. See cpw_config.h for more details.



Cpw States

Cpw is a multi-state library. This means you can create any number of Cpw contexts which get passed into each API call. For non-embedded applications, this may be overkill. There is a single/multistate compile option in cpw_config.h which switches between the multi-state API and a single-state API which does not require the passing of a pCpw context into API calls. For a replacement, a single Cpw global context is statically defined in cpw_state.h and is used internally in the single-state compile. Use this option if you are compiling a stand-alone application which only requires a single state, or if you are porting an existing GLUT application to Cpw.

The documentation below is specific to the multi-state version. All single-state API calls are identical with the exception that the initial 'pCpw cpw' parameter is not defined as the first parameter. Note, you still need to call cpwInitContext() and cpwExitContext() in the single-state library.

Multi-state / Single-state compile option:

CPW_COMPILEOPT_SINGLESTATE
(single-state currently not available in the download page version of Cpw but will be available for 1.0)



Initializing and Exiting Cpw

Cpw is safe for multistate programming. There are no global static data structures or variables contained within the source code. As such, Cpw is suitable for embedded systems or for embedding within other applications. (a web browser for example) A Cpw context holds all Cpw specific data. Cpw also frees all resources it allocates for a particular Cpw context.

bool cpwInitContext( pCpw * cpw )

cpwInitContext creates and initializes the a Cpw state context and library. It must be called before any other Cpw call is made. pCpw * cpw is a pointer to a 'pCpw' context (which is a pointer also). Init context allocates memory for the state, so all you have to do is hand in a valid pointer to a pCpw.

Single State Example:

    pCpw cpw;                                                   
    cpwInitContext( &cpw );                                     
    ..                                                          
                                                 
    cpwFreeContext( &cpw );
    exit(0);
Multistate Example:
    pCpw cpw1;                                                        
    pCpw cpw2;                                                        
                                                 
    cpwInitContext( &cpw1 );                                    
    cpwInitContext( &cpw2 );                                    
                                                 
    cpwDisplayCallback( cpw1, app1_displayCallback );           
    cpwDisplayCallback( cpw2, app2_displayCallback );           
                                                 
    cpwCreateWindowEx( cpw1, "App1 Win1", 100, 100, 300, 300 );
    cpwCreateWindowEx( cpw1, "App1 Win2", 120, 120, 300, 300 );
    cpwCreateWindowEx( cpw2, "App2 Win1", 200, 200, 300, 300 );
    cpwCreateWindowEx( cpw2, "App2 Win2", 220, 220, 300, 300 );

    ..
    while ( running ) {
        cpwMainLoopUpdate( cpw1, 1 );
        cpwMainLoopUpdate( cpw2, 1 );
    }
    ..                     

    cpwFreeContext( &cpw1 );
    cpwFreeContext( &cpw2 );
    exit(0);
bool cpwFreeContext( pCpw * cpw )

cpwFreeContext shuts down the library for the context. Open windows associated with the state will first receive a close event and then will be destroyed. After windows are destroyed, the rest of the library will be shutdown. All internal resources will be freed, including the state memory itself. pCpw will return as a null pointer after a call to cpwFreeContext.

Example use:

    pCpw cpw;              
    cpwInitContext( &cpw );
    ..                     
    cpwMainLoop( cpw );
    ..                     
    cpwFreeContext( &cpw );
    exit(0);




Cpw Errors

All Cpw calls return some sort of value indicating success or failure if they can fail. Information regarding the cause of a failure can be accessed using cpwGetLastError.

int_32 cpwGetLastError( pCpw cpw )

Returns the error code for the last Cpw error that occurred.

void cpwSetLastError( pCpw cpw, int_32 errorcode )

Sets the current Cpw error code.

Current Cpw error codes:

    cpw_error_noerror                     /* no error */
    cpw_error_unknown                     /* unknown error (cpw_fonts) */
    cpw_error_outofmemory                 /* out of memory */
    cpw_error_invalidparameter            /* invalid parameter */
    cpw_error_invalidfont                 /* invalid font file */
    cpw_error_initfailed                  /* initialization failed */
    cpw_error_createwindowfailed          /* failed to create the window */
    cpw_error_visualformatunsupported     /* draw surface format is not supported */
    cpw_error_visualformatinvalid         /* failed to set draw surface visual format */
    cpw_error_createcontextfailed         /* failed to create a gl rendering context */
    cpw_error_setcurrentcontextfailed     /* failed to set gl rendering context current */
    cpw_error_failedtosetvideo            /* video resolution format not supported */
    cpw_error_failedtogetvideo            /* could not enumerate video modes */
    cpw_error_novalidcontext              /* call occured before a valid window exists */
    cpw_error_invalidmenuid               /* invalid menu id specified */
    cpw_error_maxentriesreached           /* max menu entries reached */
    cpw_error_invalidwindowid             /* invalid window id specified */
    cpw_error_unabletoassignmenu          /* assign menu to window failed */
    cpw_error_menunotassigned             /* the menu was not assigned to the window */
    cpw_error_invalidentryid              /* invalid menu entry id */
    cpw_error_invalidjoystickid           /* invalid joystick id specified */
    cpw_error_failedtoload                /* failed to load the image file */
    cpw_error_invalidformat               /* invalid image file format */




Global User Context

Allows for the storage of a user definable context within the Cpw state structure which is accessible during execution.

bool cpwSetUserdata( pCpw cpw, pVoid userdata )

Sets the global user context.

pVoid cpwGetUserdata( pCpw cpw )

Retrieves the global user context.





Print Output Handler

bool cpwInitPrintHandler( pCpw cpw, CpwPrintHandler print )

Sets the print handler for any console based output the library produces. The default print handler sends output to stderr.

CpwPrintHandler function definition:

    void print( char * string ) 





Video Settings

Controls the localhost's desktop video resolution and color depth. Also communicates the current desktop settings.

bool cpwChangeVideoMode( pCpw cpw, CpwVideoHints hints )

Changes the current desktop resolution and color depth based on a set of hints. The localhost adapter will attempt to match the closest video mode available.

bool cpwListVideoModes( pCpw cpw, CpwVideoList * list )

Lists the localhost's available video settings. Pass a pointer to a valid CpwVideoList structure.

bool cpwFreeVideoList( pCpw cpw, CpwVideoList * list )

Frees a CpwVideoList structure after it has been allocated.

Example Use:

    void dumpVideoModes( pCpw cpw ) 
    {
        CpwVideoList list;
        int_32 count;

        if ( !cpwListVideoModes( cpw, &list ) ) return;

        count = list.size;

        while ( count >= 0 ) {

        if ( list.list[count]->active == true )

            printf( "- %dx%d, %d bits\n", list.list[count]->width,
                                        list.list[count]->height,
                                        list.list[count]->depth );
        else

            printf( "%dx%d, %d bits\n", list.list[count]->width,
                                        list.list[count]->height,
                                        list.list[count]->depth );
            count--;
        }

        cpwFreeVideoList( cpw, &list );

        return;
    }
CpwVideoList structure:
    #define MAX_VLIST 100

    struct _CpwVideoList 
    {
        CpwVideoHints * list[MAX_VLIST];
        uint_32         size;
    };
    typedef struct _CpwVideoList CpwVideoList;
CpwVideoHints structure:
    struct _CpwVideoHints 
    {
        uint_32 width;
        uint_32 height;
        uint_32 depth;
        bool    active;
    };
    typedef struct _CpwVideoHints CpwVideoHints;





Main Execution Loop

You can choose a model depending on your needs. With CpwMainLoop, Cpw controls thread execution giving the application control through the standard event, mainloop and idle callbacks.

With CpwMainLoopUpdate, Cpw's main loop becomes the application's event and window management library, only processing commands and events when the application requests it to do so.

Window events are not be processed if cpwMainLoop is not running or if cpwMainLoopUpdate is not polled regularly.

bool cpwMainLoop( pCpw cpw )

cpwMainLoop is the main window and event manager execution loop. It executes as long as the base window (id=1) exists on the screen or until the localhost os requests the application to shut down. Returns a bool indicating if there was an error during init, or during event processing.

You can create windows before or after cpwMainLoop is called. Prior to cpwMainLoop, the window will be shown, but will not send event's to the host application's event callback handlers. Windows which are created prior receive a create window event immediately after entering the main loop.

bool cpwMainLoopUpdate( pCpw cpw, uint_32 ticks )

Alternate form of cpwMainLoop which only executes mainloop functionality for a number of ticks before returning. (The mainloop and idle callbacks are not active when using cpwMainLoopUpdate.) Returns true if there were no events left to process. Returns false if all 'ticks' iterations were executed and there where still events pending. Note - timer accuracy is dependant on how often you call cpwMainLoopUpdate. For example, if you set a 100ms timer but only call cpwMainLoopUpdate every 500ms, the timer will call the application back every 500ms.

bool cpwMainLoopIsRunning( pCpw cpw )

cpwMainLoopIsRunning returns a boolean flag indicating if a thread is currently executing withint cpwMainLoop.

bool cpwBreakMainLoop( pCpw cpw )

cpwBreakMainLoop breaks a cpwMainLoop execution loop causing cpwMainLoop to return. You can re-enter cpwMainLoop if needed.

bool cpwIdleCallback( pCpw cpw, CpwIdleCallback idleCallback )

cpwIdleCallback is called when cpwMainLoop would normally call sleep due to having nothing else to do. If you set this, you should call sleep too, or your app will suck 100% of the client's cpu time, and your users will hate you. If this is not set, cpwMainLoop will call sleep( 1 milli ) instead.

The idle callback is only called when there are no timers, or events to process.

Callback definition:

    void callback( pCpw cpw )
bool cpwMainLoopCallback( pCpw cpw, CpwMainLoopCallback mlCallback, uint_32 ticks )

cpwMainLoopCallback is called from cpwMainLoop on every ticks iteration of the main execution loop. Use this callback for light tasks or joystick polling. eventsArePending will be true if there are events pending which require processing.

Callback definition:

    void callback( pCpw cpw, bool eventsArePending )





Window Display Surface Properties

bool cpwInitDisplayMode( pCpw cpw, uint_32 modes )

Sets the display surface properties to be used when creating a window. You can create numerous windows each with it's own display surface properties by calling cpwInitDisplayMode before creating a window.

Example Use:

    cpwInitDisplayMode( cpw, CPW_SURFACE_RGBA | CPW_SURFACE_DEPTH16 );
Surface Bit flag Constants:
General Surface Characteristics:

    CPW_SURFACE_RGBA     0x0000000000000001 (default)
    CPW_SURFACE_INDEX    0x0000000000000002 
    CPW_SURFACE_SINGLE   0x0000000000000004
    CPW_SURFACE_DOUBLE   0x0000000000000008 (default)
    CPW_SURFACE_ACCUM    0x0000000000000010
    CPW_SURFACE_DEPTH    0x0000000000000020 (default)
    CPW_SURFACE_STENCIL  0x0000000000000040
    CPW_SURFACE_STEREO   0x0000000000000080

Color depth specific requests:

    CPW_SURFACE_COLOR8   0x0000000000000100
    CPW_SURFACE_COLOR16  0x0000000000000200 (default)
    CPW_SURFACE_COLOR32  0x0000000000000400
    CPW_SURFACE_COLOR64  0x0000000000000800
    CPW_SURFACE_RED2     0x0000000000001000
    CPW_SURFACE_RED4     0x0000000000002000
    CPW_SURFACE_RED8     0x0000000000004000
    CPW_SURFACE_RED16    0x0000000000008000
    CPW_SURFACE_GREEN2   0x0000000000010000
    CPW_SURFACE_GREEN4   0x0000000000020000
    CPW_SURFACE_GREEN8   0x0000000000040000
    CPW_SURFACE_GREEN16  0x0000000000080000
    CPW_SURFACE_BLUE2    0x0000000000100000
    CPW_SURFACE_BLUE4    0x0000000000200000
    CPW_SURFACE_BLUE8    0x0000000000400000
    CPW_SURFACE_BLUE16   0x0000000000800000
    CPW_SURFACE_ALPHA2   0x0000000001000000
    CPW_SURFACE_ALPHA4   0x0000000002000000
    CPW_SURFACE_ALPHA8   0x0000000004000000
    CPW_SURFACE_ALPHA16  0x0000000008000000

Depth buffer specific requests:

    CPW_SURFACE_DEPTH2   0x0000000010000000
    CPW_SURFACE_DEPTH4   0x0000000020000000
    CPW_SURFACE_DEPTH8   0x0000000040000000 /* (default) */
    CPW_SURFACE_DEPTH16  0x0000000080000000
    CPW_SURFACE_DEPTH32  0x0000000100000000
    CPW_SURFACE_DEPTH64  0x0000000200000000

Accumulation buffer's color depth specific requests:

    CPW_SURFACE_ACOLOR8  0x0004000000000000
    CPW_SURFACE_ACOLOR16 0x0008000000000000
    CPW_SURFACE_ACOLOR32 0x0010000000000000
    CPW_SURFACE_ACOLOR64 0x0020000000000000
    CPW_SURFACE_ARED2    0x0000000400000000
    CPW_SURFACE_ARED4    0x0000000800000000
    CPW_SURFACE_ARED8    0x0000001000000000
    CPW_SURFACE_ARED16   0x0000002000000000
    CPW_SURFACE_AGREEN2  0x0000004000000000
    CPW_SURFACE_AGREEN4  0x0000008000000000
    CPW_SURFACE_AGREEN8  0x0000010000000000
    CPW_SURFACE_AGREEN16 0x0000020000000000
    CPW_SURFACE_ABLUE2   0x0000040000000000
    CPW_SURFACE_ABLUE4   0x0000080000000000
    CPW_SURFACE_ABLUE8   0x0000100000000000
    CPW_SURFACE_ABLUE16  0x0000200000000000
    CPW_SURFACE_AALPHA2  0x0000400000000000
    CPW_SURFACE_AALPHA4  0x0000800000000000
    CPW_SURFACE_AALPHA8  0x0001000000000000
    CPW_SURFACE_AALPHA16 0x0002000000000000

Accumulation buffer's depth buffer specific requests:

    CPW_SURFACE_ADEPTH2  0x0040000000000000
    CPW_SURFACE_ADEPTH4  0x0080000000000000
    CPW_SURFACE_ADEPTH8  0x0100000000000000
    CPW_SURFACE_ADEPTH16 0x0200000000000000
    CPW_SURFACE_ADEPTH32 0x0400000000000000
    CPW_SURFACE_ADEPTH64 0x0800000000000000
bool cpwInitDisplayModeExact( pCpw cpw, uint_32 mode, uint_32 condition, int_32 value )

Sets the specific display surface properties to be used when creating a window.

Comparitor constants for cpwInitDisplayModeExact:

    CPW_NONE
    CPW_EQUAL
    CPW_NOT_EQUAL
    CPW_LESS
    CPW_MORE
    CPW_LESS_OR_EQUAL
    CPW_MORE_OR_EQUAL
    CPW_CLOSEST
Settings flag constants for cpwInitDisplayModeExact:
    CPW_SURFACEX_ALPHA
    CPW_SURFACEX_ACCUM
    CPW_SURFACEX_RED  
    CPW_SURFACEX_GREEN
    CPW_SURFACEX_BLUE 
    CPW_SURFACEX_INDEXCOLORBUFFER
    CPW_SURFACEX_CONFORMANT
    CPW_SURFACEX_DEPTH
    CPW_SURFACEX_DOUBLE
    CPW_SURFACEX_INDEX
    CPW_SURFACEX_NUM
    CPW_SURFACEX_RGBA
    CPW_SURFACEX_RGB
    CPW_SURFACEX_LUMINANCE
    CPW_SURFACEX_STENCIL
    CPW_SURFACEX_SINGLE
    CPW_SURFACEX_STEREO
    CPW_SURFACEX_SAMPLES
    CPW_SURFACEX_SLOW
    CPW_SURFACEX_WIN32PDF
    CPW_SURFACEX_XVISUAL
    CPW_SURFACEX_XSTATICGRAY
    CPW_SURFACEX_XGRAYSCALE
    CPW_SURFACEX_XSTATICCOLOR
    CPW_SURFACEX_XPSEUDOCOLOR
    CPW_SURFACEX_XTRUECOLOR
    CPW_SURFACEX_XDIRECTCOLOR




Default Window Characteristics

bool cpwInitWindowSize( pCpw cpw, uint_32 width, uint_32 height )

Sets the initial window size used when creating a window with cpwCreateWindow. (You may also use cpwCreateWindowEx to specify these values when creating a window.)

bool cpwInitWindowPosition( pCpw cpw, uint_32 xposition, uint_32 yposition )

Sets the initial window desktop position used when creating a window with cpwCreateWindow. (You may also use cpwCreateWindowEx to specify these values when creating a window.)

bool cpwInitWindowProperty( pCpw cpw, uint_32 property, uint_32 param1, uint_32 param2 )

Used to set various window properties and drawing styles.

Window styles:

CPW_WINDOWPROP_STANDARD   - create a bordered, resizable window with 
                            a titlebar and window controls.

CPW_WINDOWPROP_NODRESSING - create a bordered, resizable window with
                            a title bar.

CPW_WINDOWPROP_POPUP      - create a non-resizable 'popup' window.
Window properties:
CPW_WINDOWPROP_POSITION     - alternative way to specific default window position.

CPW_WINDOWPROP_SIZE         - alternative way to specific default window size.

CPW_WINDOWPROP_DESKTOP      - set the default position and size to that of the desktop.

CPW_WINDOWPROP_EXPECTMENU   - the window expects a titlebar menu. creates an empty
                              menu until one is assigned.
Window border styles:
CPW_WINDOWPROP_NOBORDER

CPW_WINDOWPROP_THINBORDER

CPW_WINDOWPROP_THICKBORDER





Creating A Normal Window

uint_32 cpwCreateWindow( pCpw cpw, pChar title )

Creates a window based on the current cpwInit position, size and surface parameters. Returns the window's id. Window id's start at 1. Specifying an id of 0 in window control API calls indicates the action should occur on the current foreground window.

uint_32 cpwCreateWindowEx( pCpw cpw, pChar title, uint_32 x, uint_32 y, uint_32 width, uint_32 height )

Creates the window specified using the current cpwInit surface parameters. Returns the window's id. Window id's start at 1. Specifying an id of 0 in window control API calls indicates the action should occur on the current foreground window.





Creating A Fullscreen Window

uint_32 cpwCreateFullscreenWindow( pCpw cpw )

Creates a fullscreen window using the current cpwInit surface parameters. Returns the window's id. Window id's start at 1. Specifying an id of 0 in window control API calls indicates the action should occur on the current foreground window.

bool cpwFullscreenWindow( pCpw cpw, uint_32 id )

Converts an existing 'normal' desktop window to a fullscreen window. The existing window is usually destroyed and recreated on most platforms.



User Definable Window Contexts

Allows the user to store window specific or general application data within the Cpw state which can be accessed at a later point in execution. Userdata is stored but not manipulated by Cpw. Cpw supports the storage of one context per window created; the window id is used to retrieve the context.

bool cpwSetWindowUserdata( pCpw cpw, pVoid userdata, uint_32 id )

Sets the user definable context for the specified window. The hosting application can call cpwGetWindowUserdata at any time to retrieve the context. 'id' must be a valid window id.

pVoid cpwGetWindowUserdata( pCpw cpw, uint_32 id )

Retrieves the user definable context for a window.



Window Management

uint_32 cpwGetWindow( pCpw cpw )

Returns the id of the current foreground window.

bool cpwDestroyWindow( pCpw cpw, uint_32 id )

Closes and Destroys the window specified.

bool cpwSetWindow( pCpw cpw, uint_32 id )

Sets the rendering context of the window specified current.

bool cpwSetForegroundWindow( pCpw cpw, uint_32 id )

Moves the window specified to the foreground.

bool cpwSetWindowTitle( pCpw cpw, pChar string, uint_32 id )

Sets the title bar text of the window.

bool cpwPositionWindow( pCpw cpw, uint_32 x, uint_32 y, uint_32 id )

Positions the window on the desktop.

bool cpwReshapeWindow( pCpw cpw, uint_32 width, uint_32 height, uint_32 id )

Reshapes the window to the specified size.

bool cpwPopWindow( pCpw cpw )

Places the current foreground window at the bottom of the window z-order window stack.

bool cpwPushWindow( pCpw cpw )

Pushes the foreground window down one in the window z-order stack, replacing it with the window below.

bool cpwIconifyWindow( pCpw cpw, uint_32 id )

Iconifies the window.

bool cpwRestoreWindow( pCpw cpw, uint_32 id )

Restores a hidden or iconic window to it's original size and position.

bool cpwHideWindow( pCpw cpw, uint_32 id )

Completely hides a window from view.

bool cpwShowWindow( pCpw cpw, uint_32 id )

Shows a hidden window.

bool cpwPostRedisplay( pCpw cpw )

Posts a redisplay (paint) event to all windows.

bool cpwPostWindowRedisplay( pCpw cpw, uint_32 id )

Posts a redisplay (paint) event to the specified window.

bool cpwSwapBuffers( pCpw cpw )

Swaps the buffers on all double buffered windows.

bool cpwSwapWindowBuffers( pCpw cpw, uint_32 id )

Swaps the buffers on the specified double buffered window.

bool cpwListWindows( pCpw cpw, CpwWindowList * list )

Returns a list of CpwWindowInfo structures containing information about each open window. CPW_WINDOWLIST_MAX is defined in cpw_config.h.

  struct _CpwWindowList 
  {
    CpwWindowInfo list[CPW_WINDOWLIST_MAX];
    uint_32 size;
  };
  typedef struct _CpwWindowList  CpwWindowList;
bool cpwGetWindowInfo( pCpw cpw, CpwWindowInfo * info, uint_32 id )

Returns a filled CpwWindowInfo structure containing info about the specified window.

  struct _CpwWindowInfo
  {
    uint_16 id;
    uint_16 x;
    uint_16 y;
    uint_16 width;
    uint_16 height;
    bool    foreground;
    bool    fullscreen;
  };
  typedef struct _CpwWindowInfo  CpwWindowInfo;
Example Use:
    CpwWindowInfo info;
    cpwGetWindowInfo( cpw, &info, 1 );




Global Window Event Callbacks

Global events callbacks receive events which are not handled by window specific event callback. (See "Window Specific Event Callbacks" below) Internally, events which do have a global or window specific callback registered call the default callbacks defined in cpw_defaultcallbacks.c. (In most cases, default callbacks are nop's.)

bool cpwCreateCallback( pCpw cpw, CpwCreateCallback createCallback )

Sets the application's global window create and destroy event handler function.

Callback definition:

    void function( pCpw cpw, uint_32 windowid, bool flag )
'flag' is true if the window is being created, false if it is being destroyed.

bool cpwDisplayCallback( pCpw cpw, CpwDisplayCallback displayCallback )

Sets the application's global window redisplay (paint) event handler function.

Callback definition:

    void function( pCpw cpw, uint_32 windowid )
bool cpwPositionCallback( pCpw cpw, CpwPositionCallback positionCallback )

Sets the application's global window reposition event handler function. Movement of a window on the deskop causes the event.

Callback definition:

    void function( pCpw cpw, uint_32 windowid, uint_32 x, uint_32 y )
'x' and 'y' are in desktop coordinates. Use cpwGet to retrieve the desktop resolution.

bool cpwReshapeCallback( pCpw cpw, CpwReshapeCallback reshapeCallback )

Sets the application's global window frame reshaping event handler.

Callback definition:

    void function( pCpw cpw, uint_32 windowid, uint_32 width, uint_32 height )
bool cpwKeyboardCallback( pCpw cpw, CpwKeyboardCallback keyboardCallback )

Sets the application's global ascii key press event handler function. This handler receives (non system key) ascii key presses (a-z, 1-0, etc) and numeric keypad key strokes when the numlock is enabled.

Callback definition:

    void function( pCpw cpw, uint_32 windowid, uint_32 asciicode, 
                   uint_32 keystate, uint_32 cursorxpos, uint_32 cursorypos )
Key state constants:
    CPW_KEYMOD_DOWN
    CPW_KEYMOD_UP
'keystate' is a constant - either CPW_KEYMOD_DOWN or CPW_KEYMOD_UP, representing whether the key is being pressed down or is being released. 'asciicode' is the ascii or Unicode key value for the specified key.

bool cpwSystemKeyboardCallback( pCpw cpw, CpwSystemKeyboardCallback skeyCallback )

Sets the application's global system key, key press event handler.

The SystemKeyboardCallback handles the following keys - capslock, shift, control, alt, escape, tab, backspace, enter key, arrow keys, page control, and the function keys.

Callback definition:

    void function( pCpw cpw, uint_32 windowid, uint_32 keycode, uint_32 keystate, 
                   uint_32 cursorxpos, uint_32 cursorypos )
Callback key state constants:
    CPW_KEYMOD_DOWN
    CPW_KEYMOD_UP
System key constants:
function keys -

    CPW_KEY_F1
    CPW_KEY_F2
    CPW_KEY_F3
    CPW_KEY_F4
    CPW_KEY_F5
    CPW_KEY_F6
    CPW_KEY_F7
    CPW_KEY_F8
    CPW_KEY_F9
    CPW_KEY_F10
    CPW_KEY_F11
    CPW_KEY_F12

arrow keys -

    CPW_KEY_LEFT
    CPW_KEY_UP  
    CPW_KEY_RIGHT
    CPW_KEY_DOWN 

cursor control keys -

    CPW_KEY_PAGE_UP  
    CPW_KEY_PAGE_DOWN
    CPW_KEY_HOME     
    CPW_KEY_END      
    CPW_KEY_INSERT   
    CPW_KEY_DELETE   

misc. system keys -

    CPW_KEY_CAPSLOCK   
    CPW_KEY_SHIFT  
    CPW_KEY_CONTROL
    CPW_KEY_ALT    
    CPW_KEY_ESCAPE 
    CPW_KEY_TAB    
    CPW_KEY_BACKSPACE
    CPW_KEY_ENTER  

numeric keypad keys -

    CPW_KEY_MULTIPLY
    CPW_KEY_ADD     
    CPW_KEY_SEPERATOR
    CPW_KEY_SUBTRACT 
    CPW_KEY_DECIMAL  
    CPW_KEY_DIVIDE   
    CPW_KEY_PAUSE    
bool cpwMouseClickCallback( pCpw cpw, CpwMouseClickCallback mouseclickCallback )

Sets the application's global mouse button click event handler function.

Callback definition:

    void function( pCpw cpw, uint_32 windowid, uint_32 button, uint_32 buttonstate, 
                   uint_32 cursorxpos, uint_32 cursorypos )
Mouse button constants:
    CPW_BUTTON_LEFT
    CPW_BUTTON_MIDDLE
    CPW_BUTTON_RIGHT
Mouse button state constants:
    CPW_MOUSE_DOWN
    CPW_MOUSE_UP
    CPW_BUTTON_ROLL
bool cpwMouseDragCallback( pCpw cpw, CpwMouseDragCallback mousedragCallback )

Sets the application's global mouse click and drag event handler function.

Callback definition:

    void function( pCpw cpw, uint_32 windowid, uint_32 button, uint_32 cursorxpos, 
                   uint_32 cursorypos )
Mouse button constants:
    CPW_BUTTON_LEFT
    CPW_BUTTON_MIDDLE
    CPW_BUTTON_RIGHT
bool cpwMouseMoveCallback( pCpw cpw, CpwMouseMoveCallback mousemoveCallback )

Sets the application's global mouse movement event handler function.

Callback definition:

    void function( pCpw cpw, uint_32 windowid, uint_32 cursorxpos, uint_32 cursorypos )
bool cpwMouseEntryCallback( pCpw cpw, CpwMouseEntryCallback mouseentryCallback )

Sets the application's global mouse window entry and exit event handler function.

Callback definition:

    void function( pCpw cpw, uint_32 windowid, uint_32 entrystate )
Mouse entry state constants:
    CPW_MOUSE_ENTER
    CPW_MOUSE_LEAVE
bool cpwVisibilityCallback( pCpw cpw, CpwVisibilityCallback visibilityCallback )

Sets the application's global window visibility changes event handler.

Callback definition:

    void function( pCpw cpw, uint_32 windowid, uint_32 visstate )
Window visibility state constants:
    CPW_HIDE
    CPW_SHOW
    CPW_GAINEDFOCUS
    CPW_LOSTFOCUS
    CPW_ICONIC
    CPW_RESTORED




Window Specific Event Callbacks

Window specific event callbacks receive events specific to a window. If a particular window's event handler does not have a window specific event handler registered, the global event callback is called. (See "Global Window Event Callbacks" above)

Window specific events require an additional window id lookup when processing an event. If you are porting a GLUT application to Cpw or simply do not make use of window specific events, there is a compile option in cpw_config.h which turns the extra id lookup off.

Window specific events compile directive:

CPW_COMPILEOPT_WINDOWSPECIFICEVENTS
bool cpwWindowCreateCallback( pCpw cpw, CpwCreateCallback createCallback, uint_32 windowid )

Sets the window's create and destroy event handler function.

Callback definition:

    void function( pCpw cpw, bool flag )
'flag' is true if the window is being created, false if it is being destroyed.

bool cpwWindowDisplayCallback( pCpw cpw, CpwDisplayCallback displayCallback )

Sets the window's redisplay (paint) event handler function.

Callback definition:

    void function( pCpw cpw )
bool cpwWindowPositionCallback( pCpw cpw, CpwPositionCallback positionCallback )

Sets the window's reposition event handler function. Movement of the entire window on the deskop causes these events.

Callback definition:

    void function( pCpw cpw, uint_32 x, uint_32 y )
bool cpwWindowReshapeCallback( pCpw cpw, CpwReshapeCallback reshapeCallback )

Sets the window's frame reshaping event handler.

Callback definition:

    void function( pCpw cpw, uint_32 width, uint_32 height )
bool cpwWindowKeyboardCallback( pCpw cpw, CpwKeyboardCallback keyboardCallback )

Sets the window's ascii key press event handler function. This handler receives (non system key) ascii key presses (a-z, 1-0, etc) and numeric keypad key strokes when the numlock is enabled.

Callback definition:

    void function( pCpw cpw, uint_32 asciicode, uint_32 keystate, 
                   uint_32 cursorxpos, uint_32 cursorypos )
Key state constants:
    CPW_KEYMOD_DOWN
    CPW_KEYMOD_UP
'keystate' is a constant - either CPW_KEYMOD_DOWN or CPW_KEYMOD_UP, representing whether the key is being pressed down or is being released. 'asciicode' is the ascii or Unicode key value for the specified key.

bool cpwWindowSystemKeyboardCallback( pCpw cpw, CpwSystemKeyboardCallback skeyCallback )

Sets the window's system key, key press event handler.

The SystemKeyboardCallback handles the following keys - capslock, shift, control, alt, escape, tab, backspace, enter key, arrow keys, page control, and the function keys.

Callback definition:

    void function( pCpw cpw, uint_32 keycode, uint_32 keystate, 
                   uint_32 cursorxpos, uint_32 cursorypos )
Callback key state constants:
    CPW_KEYMOD_DOWN
    CPW_KEYMOD_UP
System key constants:
function keys -

    CPW_KEY_F1
    CPW_KEY_F2
    CPW_KEY_F3
    CPW_KEY_F4
    CPW_KEY_F5
    CPW_KEY_F6
    CPW_KEY_F7
    CPW_KEY_F8
    CPW_KEY_F9
    CPW_KEY_F10
    CPW_KEY_F11
    CPW_KEY_F12

arrow keys -

    CPW_KEY_LEFT
    CPW_KEY_UP  
    CPW_KEY_RIGHT
    CPW_KEY_DOWN 

cursor control keys -

    CPW_KEY_PAGE_UP  
    CPW_KEY_PAGE_DOWN
    CPW_KEY_HOME     
    CPW_KEY_END      
    CPW_KEY_INSERT   
    CPW_KEY_DELETE   

misc. system keys -

    CPW_KEY_CAPS   
    CPW_KEY_SHIFT  
    CPW_KEY_CONTROL
    CPW_KEY_ALT    
    CPW_KEY_ESCAPE 
    CPW_KEY_TAB    
    CPW_KEY_BACKSPACE
    CPW_KEY_ENTER  

numeric keypad keys -

    CPW_KEY_MULTIPLY
    CPW_KEY_ADD     
    CPW_KEY_SEPERATOR
    CPW_KEY_SUBTRACT 
    CPW_KEY_DECIMAL  
    CPW_KEY_DIVIDE   
    CPW_KEY_PAUSE    
bool cpwWindowMouseClickCallback( pCpw cpw, CpwMouseClickCallback mouseclickCallback )

Sets the window's mouse button click event handler function.

Callback definition:

    void function( pCpw cpw, uint_32 button, uint_32 buttonstate, 
                   uint_32 cursorxpos, uint_32 cursorypos )
Mouse button constants:
    CPW_BUTTON_LEFT
    CPW_BUTTON_MIDDLE
    CPW_BUTTON_RIGHT
Mouse button state constants:
    CPW_MOUSE_DOWN
    CPW_MOUSE_UP
    CPW_BUTTON_ROLL
bool cpwWindowMouseDragCallback( pCpw cpw, CpwMouseDragCallback mousedragCallback )

Sets the window's mouse click and drag event handler function.

Callback definition:

    void function( pCpw cpw, uint_32 button, uint_32 cursorxpos, 
                   uint_32 cursorypos )
Mouse button constants:
    CPW_BUTTON_LEFT
    CPW_BUTTON_MIDDLE
    CPW_BUTTON_RIGHT
bool cpwWindowMouseMoveCallback( pCpw cpw, CpwMouseMoveCallback mousemoveCallback )

Sets the window's mouse movement event handler function.

Callback definition:

    void function( pCpw cpw, uint_32 cursorxpos, uint_32 cursorypos )
bool cpwWindowMouseEntryCallback( pCpw cpw, CpwMouseEntryCallback mouseentryCallback )

Sets the window's mouse window entry and exit event handler function.

Callback definition:

    void function( pCpw cpw, uint_32 entrystate )
Mouse entry state constants:
    CPW_MOUSE_ENTER
    CPW_MOUSE_LEAVE
bool cpwWindowVisibilityCallback( pCpw cpw, CpwVisibilityCallback visibilityCallback )

Sets the window's window visibility changes event handler.

Callback definition:

    void function( pCpw cpw, uint_32 visstate )
Window visibility state constants:
    CPW_HIDE
    CPW_SHOW
    CPW_GAINEDFOCUS
    CPW_LOSTFOCUS
    CPW_ICONIC
    CPW_RESTORED





Window Cursors

bool cpwSetCursor( pCpw cpw, CpwCursor cursor, uint_32 id )

Sets the cursor for the specified window. The cursor is set when the mouse cursor enters the window area and the window is in the foreground.

Mouse Cursor Constants:

    CursorArrow
    CursorHand 
    CursorNo   
    CursorQuestion
    CursorBeam    
    CursorWait    
    CursorCrosshair
    CursorNone     
    CursorSizeNSEW 
    CursorSizeNS   
    CursorSizeNeSw 
    CursorSizeEW   
    CursorSizeSeNw 
    CursorCustom   
bool cpwCenterCursor( pCpw cpw, uint_32 id )

Centers the cursor in the window's client area. Only works if the window specified is in the foreground.

bool cpwPositionCursor( pCpw cpw, uint_32 x, uint_32 y, uint_32 id )

Positions the cursor in the window's client area. Only works if the window specified is in the foreground.





Mouse and Keyboard Polling

Cpw supports both event driven and polled user input. Developers can use the global and window event callbacks for mouse and keyboard input. They may also poll these devices for their state information at any time during execution.

bool cpwMouseCapabilities( pCpw cpw, CpwMouseCapabilities * mcaps )

Returns information about the client's mouse capabilities. Pass a pointer to a valid CpwMouseCapabilities structure.

  struct _CpwMouseCapabilities
  {
    bool xy; /* always true unless there is no mouse attached to the system */
    bool z;  /* the mouse supports a 3rd axis or mouse wheel */
    uint_32 buttons; /* the number of buttons the mouse supports */
  };
  typedef struct _CpwMouseCapabilities CpwMouseCapabilities;
bool cpwMouseState( pCpw cpw, CpwMouseInfo * info )

Returns the current state of the mouse. Pass a pointer to a valid CpwMouseInfo structure. Mouse positional information is relative to the last call to cpwMouseState.

  struct _CpwMouseInfo
  {
    int_32 x;
    int_32 y;
    int_32 z;
    bool   buttons[CPW_MAX_BUTTONS];
  };
  typedef struct _CpwMouseInfo CpwMouseInfo;
bool cpwKeyState( pCpw cpw, CpwKeyConstant key )

Returns true or false indicating the state of the specified key. Pass a valid Cpw system key constant or one of the following ASCII key state constants.

ASCII key constants:

  CPW_KEY_1
  CPW_KEY_2
  CPW_KEY_3
  CPW_KEY_4
  CPW_KEY_5
  CPW_KEY_6
  CPW_KEY_7
  CPW_KEY_8
  CPW_KEY_9
  CPW_KEY_0

  CPW_KEY_LCONTROL
  CPW_KEY_RCONTROL
  CPW_KEY_LSHIFT
  CPW_KEY_RSHIFT
  CPW_KEY_LALT
  CPW_KEY_RALT

  CPW_KEY_MINUS
  CPW_KEY_EQUALS
  CPW_KEY_LBRACKET
  CPW_KEY_RBRACKET
  CPW_KEY_SEMICOLON
  CPW_KEY_APOSTROPHE
  CPW_KEY_QUOTE
  CPW_KEY_COMMA
  CPW_KEY_PERIOD
  CPW_KEY_SLASH
  CPW_KEY_BACKSLASH
  CPW_KEY_SPACE

  CPW_KEY_A
  CPW_KEY_B
  CPW_KEY_C
  CPW_KEY_D
  CPW_KEY_E
  CPW_KEY_F
  CPW_KEY_G
  CPW_KEY_H
  CPW_KEY_I
  CPW_KEY_J
  CPW_KEY_K
  CPW_KEY_L
  CPW_KEY_M
  CPW_KEY_N
  CPW_KEY_O
  CPW_KEY_P
  CPW_KEY_Q
  CPW_KEY_R
  CPW_KEY_S
  CPW_KEY_T
  CPW_KEY_U
  CPW_KEY_V
  CPW_KEY_W
  CPW_KEY_X
  CPW_KEY_Y
  CPW_KEY_Z





Timers

bool cpwTimerCallback( pCpw cpw, uint_32 milli, uint_32 timerid, bool recurring, CpwTimerCallback timerCallback )

Creates a new timer. 'milli' is the timer's timeout value in milliseconds. 'timerid' is a user definable id value handed back to the timer callback function. 'recurring' is a boolean flag indicating whether the timer is a recurring timer or one-shot.

Callback definition:

    void function( pCpw cpw, uint_32 timerid )

bool cpwKillTimer( pCpw cpw, uint_32 timerid )

Kills a recurring timer.





Event Stack

bool cpwFilterEvent( pCpw cpw, CpwWindowEvent eventType, bool flag )

Turns event filtering for a specific event on or off. Returns the previous filter value for the particular event.

Event Constants:

    CPW_NO_EVENT
    CPW_CREATE_EVENT
    CPW_DESTROY_EVENT
    CPW_MOUSECLICK_EVENT
    CPW_MOUSEMOTION_EVENT
    CPW_MOUSEDRAG_EVENT
    CPW_MOUSEENTRY_EVENT
    CPW_KEYBOARD_EVENT
    CPW_SYSKEYBOARD_EVENT
    CPW_POSITION_EVENT
    CPW_DISPLAY_EVENT
    CPW_VISIBILITY_EVENT
    CPW_RESHAPE_EVENT
    CPW_MENUSELECT_EVENT
CpwWindowEvent cpwNextEvent( pCpw cpw )

Returns a CpwWindowEvent constant indicating the next event to be delivered.

Event Constants:

    CPW_NO_EVENT
    CPW_CREATE_EVENT
    CPW_DESTROY_EVENT
    CPW_MOUSECLICK_EVENT
    CPW_MOUSEMOTION_EVENT
    CPW_MOUSEDRAG_EVENT
    CPW_MOUSEENTRY_EVENT
    CPW_KEYBOARD_EVENT
    CPW_SYSKEYBOARD_EVENT
    CPW_POSITION_EVENT
    CPW_DISPLAY_EVENT
    CPW_VISIBILITY_EVENT
    CPW_RESHAPE_EVENT
    CPW_MENUSELECT_EVENT
CpwWindowEvent cpwNextWindowEvent( pCpw cpw, uint_32 id )

Returns a CpwWindowEvent constant indicating the next event to be delivered for the specified window.

bool cpwClearEvents( pCpw cpw )

Clears all events in the event stack.

bool cpwClearEvent( pCpw cpw, CpwWindowEvent event )

Clears all of the events specified in the event stack.

bool cpwClearWindowEvents( pCpw cpw, uint_32 id )

Clears all events in the event stack for the specified window.

bool cpwClearWindowEvent( pCpw cpw, CpwWindowEvent event, uint_32 id )

Clears all of the events specified in the event stack for the specified window.

bool cpwPopEvent( pCpw cpw )

Discards the top event off the event stack.

int_32 cpwStackDepth( pCpw cpw )

Returns the current number of events pending.



Popup and Titlebar Menus

Cpw supports both client area popup menus and window titlebar menus. Menus can have a one to many relationship with windows; you can assign a single menu to multiple locations and on multiple windows. All menu resources are destroyed when Cpw exits, or when the user calls cpwDestroyMenu.

uint_32 cpwCreateMenu( pCpw cpw, CpwMenuCallback callback )

Creates a new top level menu and returns an identifier to it. The menu may be used as a popup or titlebar menu, or both and can be assigned to multiple windows.

Callback definition:

    void function( pCpw cpw, uint_32 windowid, uint_32 menuid, uint_32 entryid )
uint_32 cpwCreateSubMenu( pCpw cpw )

Creates a new sub menu and returns an identifier for it. Sub menus are identical to menus except they do not have a callback associated with them. They are expected to be embedded within top level menus. The identifier is only for editing the menu or inserting it into a top level menu.

bool cpwDestroyMenu( pCpw cpw, uint_32 menuid )

Destroys the resources associated with a menu or sub menu. (All menu resources are automatically destroyed when Cpw exits.)

bool cpwAddMenuEntry( pCpw cpw, uint_32 menuid, pChar title, uint_32 entryid, bool checked )

Inserts a new entry into a menu. 'entryid' is the value handed back to the callback when a user selects the entry. Entries are added to a menu in a top down fashion.

bool cpwAddMenuSeperator( pCpw cpw, uint_32 menuid, uint_32 entryid )

Inserts a new seperator into a menu. 'entryid' is the value used when editing the menu. Seperators can not be 'selected' and therefore do not generate callbacks.

bool cpwAddSubMenu( pCpw cpw, uint_32 menuid, pChar title, uint_32 submenuid, uint_32 entryid )

Inserts a new sub menu entry into a menu. 'entryid' is the value used when editing the menu. Sub menu titles can not be 'selected' and therefore do not generate callbacks.

bool cpwEditMenuItem( pCpw cpw, uint_32 menuid, uint_32 entryid, uint_32 newentryid, bool seperator, pChar newtitle, uint_32 newsubmenu )

Changes the attributes of an existing menu entry. The call will override all previous settings. Editing menus is time consuming, and should not be carried out based on user actions. To create different menu's based on the current state of your application, create multiple menus and assigned them to a window at the appropriate time.

bool cpwRemoveMenuItem( pCpw cpw, uint_32 menu, uint_32 entryid )

Removes a menu entry from a menu. You can not insert a new entry to replace an entry you have removed. Editing menus are time consuming, and should not be carried out based on user actions. To create different menu's based on the current state of your application, create multiple menus and assigned them to a window at the appropriate time.

bool cpwAssignMenuToWindow( pCpw cpw, uint_32 menuid, uint_32 winid )

Assigns a top level menu to a window's titlebar and displays it. Once a menu is assigned, menu selections will generate callbacks. Note that the callback function handler receives three parameters, the 'windowid', the 'menuid' and the 'entryid'. The window id is the id of the window the menu was selected in. (You can assign a single menu to multiple windows.) The menuid is the menu identifier of the top level menu containing all entries and sub menus. Sub menu identifiers are not sent to the callback, only top level menu identifiers. When creating sub menus, make sure your entry identifiers are unique across all entries in the top level menu the sub menu is contained within.

To seamlessly replace an entire menu, assign the new menu to the window while the old menu is still in place.

bool cpwUnassignMenu( pCpw cpw, uint_32 winid )

Removes a titlebar menu from a window. Does not destroy the resources associated with the menu and it's sub menus.

bool cpwAttachMenuToButton( pCpw cpw, uint_32 menuid, uint_32 button, uint_32 winid )

Assigns a popup menu to a particular mouse click for the specified window. Use the standard cpw mouse button constants for 'button'. 'winid' must be a valid window identifier. You can attach a single menu to more than one window, and to more than one mouse click.

bool cpwDetachMenu( pCpw cpw, uint_32 button, uint_32 winid )

Removes a popup menu button assignment for a particular window.

bool cpwCheckMenuEntry( pCpw cpw, uint_32 menuid, uint_32 entryid )

If the menu entry is not checked, adds a check mark to the entry. 'menuid' can only be a top level menu identifier. sub menu identifiers will not work.

For platforms which do not support checkmarked menus, the checkmark will not be displayed. The checkmark's state is tracked internally by Cpw and is valid regardless.

bool cpwUncheckMenuEntry( pCpw cpw, uint_32 menuid, uint_32 entryid )

If the menu entry is checked, removes a check mark from the entry. 'menuid' can only be a top level menu identifier. sub menu identifiers will not work.

For platforms which do not support checkmarked menus, the checkmark will not be displayed. The checkmark's state is tracked internally by Cpw and is valid regardless.

bool cpwMenuEntryChecked( pCpw cpw, uint_32 menuid, uint_32 entryid )

Returns a flag indicating whether or not the entry has a checkmark. 'menuid' can only be a top level menu identifier. sub menu identifiers will not work.

For platforms which do not support checkmarked menus, the checkmark will not be displayed. The checkmark's state is tracked internally by Cpw and is valid regardless.

Example Use:

    topmenu1 = cpwCreateMenu( cpw, menuselect );
    topmenu2 = cpwCreateMenu( cpw, menuselect );

    submenu1 = cpwCreateSubMenu( cpw );
    submenu2 = cpwCreateSubMenu( cpw );

    cpwAddMenuEntry( cpw, submenu1, "Test A", 1, true );
    cpwAddMenuEntry( cpw, submenu1, "Test B", 2, true );
    cpwAddMenuEntry( cpw, submenu1, "Test C", 3, true );
    cpwAddMenuSeperator( cpw, submenu1, 0 );
    cpwAddMenuEntry( cpw, submenu1, "Test 1", 4, false );
    cpwAddMenuEntry( cpw, submenu1, "Test 2", 5, false );
    cpwAddMenuEntry( cpw, submenu1, "Test 3", 6, false );

    cpwAddMenuEntry( cpw, submenu2, "My", 7, true );
    cpwAddMenuSeperator( cpw, submenu2, 0 );
    cpwAddMenuEntry( cpw, submenu2, "Car", 8, false );
    cpwAddMenuSeperator( cpw, submenu2, 0 );
    cpwAddMenuEntry( cpw, submenu2, "Is", 9, true );
    cpwAddMenuSeperator( cpw, submenu2, 0 );
    cpwAddMenuEntry( cpw, submenu2, "Silver!", 10, false );

    cpwAddSubMenu( cpw, topmenu1, "Menu 1", submenu1, 11 );
    cpwAddSubMenu( cpw, topmenu1, "Menu 2", submenu2, 12 );

    cpwAddSubMenu( cpw, topmenu2, "Menu 1", submenu1, 13 );
    cpwAddSubMenu( cpw, topmenu2, "Menu 2", submenu2, 13 );

    cpwAssignMenuToWindow( cpw, topmenu1, win1 );
    cpwAttachMenuToButton( cpw, topmenu2, CPW_BUTTON_RIGHT, win2 );

    void menuselect( pCpw cpw, uint_32 winid, uint_32 menuid, uint_32 entryid )
    {
        printf( "menu:%u item:%u\n", menuid, entryid );    
    
        if ( cpwMenuEntryChecked( cpw, menuid, entryid ) ) {

            printf("checked.\n");
            cpwUncheckMenuEntry( cpw, menuid, entryid );

        } else {

            printf("notchecked.\n");
            cpwCheckMenuEntry( cpw, menuid, entryid );

        }
    }




Loading and Saving Images

Cpw's image routines support the loading of bitmap images (BMP's), and the loading and saving of Targa (TGA) images. The image routines also support easy image resizing, texture fitting, and taking screenshots. The image library is meant to to be small, simple and portable. If your looking for more robust functionality you should consider using an external image management library such as devIL.

bool cpwLoadImage( pCpw cpw, CpwImage * image, CpwImageType type, pChar filename, bool texturefit )

Loads a TGA or BMP file into an image buffer. TGA support includes 24 and 32 bit images. BMP support includes 8, 16, and 32 bit images.

Image type constants:

  enum _CpwImageType
  {
      CPW_IMAGEFORMAT_TGA = 1,
      CPW_IMAGEFORMAT_BMP = 2,
  };
  typedef enum _CpwImageType CpwImageType;

Image buffer structure:

  struct _CpwImage
  {
    uint_32 width;
    uint_32 height;
    uint_32 depth;      /* 3 (rgb), 4 (rgba) */
    pChar   data;
  };
  typedef struct _CpwImage CpwImage;

bool cpwSaveImage( pCpw cpw, CpwImage * image, pChar filename )

Saves a RGB or RGBA image buffer as a 24 or 32 bit TGA file in the current working directory.

bool cpwFreeImage( pCpw cpw, CpwImage * image )

Free's the resources stored in an image buffer by calling cpwfree on the data member.

bool cpwScreenShot( pCpw cpw, CpwImage * image )

Creates an image buffer of suitable size and copies the current gl context's frame buffer into the image buffer. Pixel data is stored in RGB format.

bool cpwResizeImage( pCpw cpw, CpwImage * image, uint_32 width, uint_32 height )

Resizes an image buffer using gluScaleImage.

bool cpwTextureFit( pCpw cpw, CpwImage * image )

Fits an image buffer to a width and height suitable for OpenGL texture rendering. (64^n)





Fonts

Cpw uses the Freetype 2.0 font rendering library for fonts. As such, you can display any True Type font within a Cpw window.

CpwFontFace cpwLoadFont( pCpw cpw, pChar fontname, int_32 location, pChar fontpath, pChar cachelist )

Load a font face into memory. 'fontname' is the file name of the True Type font. 'location' is either CPW_FONTLOC_HOST or CPW_FONTLOC_RELATIVE. If CPW_FONTLOC_RELATIVE is specified, 'fontpath' should contains a valid application relative directory name where the font file is located. If CPW_FONTLOC_HOST is specified, Cpw looks for the font in the localhost's default font directory if one exists. 'cachelist' should be null. (Caching is not implemented yet.)

bool cpwUnloadFont( pCpw cpw, CpwFontFace font )

Unloads a font face.

int_32 cpwFontMode( pCpw cpw, int_32 mode, int_32 val )

Sets font rendering characteristics. See the table below for specific options that can be set.

Font Render Modes:

CPW_FONTOPT_PIXELMAP Render using pixelmap mode. Pixel map fonts are drawn directly to the framebuffer using glDrawPixels at the current raster position. Pixel width is dependant on the glformat option set below. If a format that uses color is specified the current gl color will be used. This is current the only mode supported and is the default mode.

val = ignored

Rendering Options:

CPW_FONTOPT_PIXELMAP_GLFORMAT the pixel format for calls to glDrawPixels when rendering pixel mapped fonts with cpDrawFont.
val = gl pixel format constant
default = GL_LUMINANCE

Layout Options:

CPW_FONTOPT_SIZE sets the size in points of the font face.
val = positive int value >= 1
default = 16
CPW_FONTOPT_FTSIZE sets the size of the font face to Freetype 26.6 pixels. 1 point = 64 Freetype pixels.
val = positive int value >= 1
CPW_FONTOPT_SPACING the character spacing multiplier.
val = 0.0 and up
default = 1
CPW_FONTOPT_KERN sets kerning advance on or off. Note: kerning is not supported if the font file does not support it.
val = true/false
default = false
CPW_FONTOPT_SCREENWIDTH the current display screen's width in dpi.
val = int width
default = 72
CPW_FONTOPT_SCREENHEIGHT the current display screen's height in dpi.
val = int width
default = 72
CPW_FONTOPT_LAYOUTDEBUG Turns bufferedfont character layout debug lines on. Lines are drawn around each character's rectangle and the entire texture.

bool cpwDrawFont( pCpw cpw, CpwFontFace font, pChar string, bool drawflag )

Draws a font string using the current render mode directly to the screen. 'string' should be a null terminated string. if 'drawflag' is true, drawing will occur. If it is false, drawing will not occur but the raster position will be advanced accordingly.

Example cpwDrawFont Use:

    static CpwFontFace font;

    void draw( pCpw cpw, uint_32 id )
    {
        glRasterPos2d( 1, 1 );
        cpwDrawFont( cpw, font, "Cpw@Mathies.Com", 1 );
    }

    void main() 
    {
        ..

        cpwFontMode( cpw, CPW_FONTOPT_PIXELMAP, 0 );
        cpwFontMode( cpw, CPW_FONTOPT_KERN, 0 );
        cpwFontMode( cpw, CPW_FONTOPT_ALIGNLEFT, 0 );
        cpwFontMode( cpw, CPW_FONTOPT_SIZE, 12 );
        cpwFontMode( cpw, CPW_FONTOPT_PIXELMAP_GLFORMAT, GL_RGB );

        font = cpwLoadFont( cpw, "TIMES.TTF", cpw_fontopt_local, "", "" );

        cpwMainLoop( cpw );

        cpwFreeContext( &cpw );
        exit(0);
    }

bool cpwGetFontBBox( pCpw cpw, CpwFontFace font, pChar string, CpwFontBBox * bbox )

Fills a CpwFontBBox with the specified string's dimensions based on the current font options and alignment.

CpwFontBBox structure:

    struct  _CpwFontBBox
    {
        int_32 width;
        int_32 height;
        int_32 offsetx;
        int_32 offsety;
    };
    typedef struct _CpwFontBBox CpwFontBBox;
The CpwFontBBox structure is used to hold a font string's bounding box, i.e., the width and maximum height of the string in pixels. 'offset' is the space from the lower left of the box to the baseline of the of the string. The baseline is the 'virtual' line drawn through the text which all characters in the string rest on.

bool cpwDrawBufferedFont( pCpw cpw, CpwFontFace font, pChar string, CpwFontBuffer * buffer )

Creates a new buffer suitable for holding an image of the string, and renders the string into the buffer. Pass a valid pointer to a CpwFontBuffer structure. Font buffers are a useful way of creating generic bitmaps used in subsequent OpenGL operation such as frame buffer writes, and in texture mapping.

Note! You must free a buffer returned by cpwDrawBufferedFont with cpwFreeBufferedFont.

bool cpwFreeBufferedFont( pCpw cpw, CpwFontBuffer * buffer )

Frees the data contained within a CpwFontBuffer by calling cpwfree on the buffer's 'data' member.

Example cpwDrawBufferedFont Use:

    static CpwFontBuffer cpwbuffer;
    static CpwFontFace font;

    void draw( pCpw cpw, uint_32 id )
    {
        glRasterPos2d( 1, 1 );
        glDrawPixels( cpwbuffer.w, cpwbuffer.h, cpwbuffer.glformat, GL_UNSIGNED_BYTE, cpwbuffer.data );
    }

    void main() 
    {
        ..

    glPixelStorei( GL_UNPACK_LSB_FIRST, GL_FALSE );
    glPixelStorei( GL_UNPACK_ALIGNMENT, 1 );

    cpwFontMode( cpw, CPW_FONTOPT_PIXELMAP, 0 );
    cpwFontMode( cpw, CPW_FONTOPT_ALIGNLEFT, 0 );
    cpwFontMode( cpw, CPW_FONTOPT_SIZE, 30 );
    cpwFontMode( cpw, CPW_FONTOPT_KERN, 1 );
    cpwFontMode( cpw, CPW_FONTOPT_PIXELMAP_GLFORMAT, GL_RGB );
    cpwFontMode( cpw, CPW_FONTOPT_LAYOUTDEBUG, 0 );
    cpwFontMode( cpw, CPW_FONTOPT_SPACING, 1 );

    glColor3f( 0.0, 1.0, 0.0 );

    font = cpwLoadFont( cpw, "times.ttf", CPW_FONTLOC_HOST, "", "" );

    /* pre-render our font string into a buffer */

    cpwDrawBufferedFont( cpw, font, "Hello", &cpwbuffer );

    cpwMainLoop( cpw );

    /* free the font buffer */

    cpwFreeBufferedFont( cpw, &cpwbuffer );

    cpwFreeContext( &cpw );

    return 0;
    }
uint_32 cpwListFonts( pCpw cpw, CpwFontList * list, pChar searchtoken, uint_32 location )

Lists fonts avaialble in either a relative directory or on the localhost. 'location' is either CPW_FONTLOC_HOST or CPW_FONTLOC_RELATIVE. 'searchtoken' contains a standard file search token. e.g. "*.ttf"

bool cpwFreeFontList( pCpw cpw, CpwFontList* list )

Frees the resources associated with a font list.





Joysticks

Cpw joystick access is robust. Cpw supports most of the modern joystick capabilities. Information about a joystick and it's corresponding data is communicated through a set of c structures passed into and out of various calls. A set of useful macros are defined in cpw_macros.h to make accessing joystick information less complex.

bool cpwInitJoysticks( pCpw cpw, CpwJoystickList * list )

Initializes 1 or 2 joysticks. CpwJoystickList should contain valid ranges information and 'list.joysticks' should be set to the number of joysticks the application would like access too.

Returns true if a joystick (or joysticks) are found and sets 'joysticks' to the number found. Returns each joystick's capabilities in 'list.caps' structure.

bool cpwJoystickCallback( pCpw cpw, CpwJoystickCallback callback, uint_32 joyid, CpwJoystickInfo * info, uint_32 delay )

Creates a global joystick callback. 'delay' specifies the time in milliseconds between callback events. Internally the callback will call cpwJoystickPoll prior to the callback.

Callback definition:

    void function( pCpw cpw, CpwJoystickInfo * info ); 
bool cpwJoystickPing( pCpw cpw, uint_32 joyid )

Forces a joystick callback event.

bool cpwJoystickPoll( pCpw cpw, CpwJoystickInfo * info )

Polls the joystick for it's current state. Pass a valid pointer to a CpwJoystickInfo structure.

Example Use:

    /* joystick info */
    static CpwJoystickList list;
    static CpwJoystickInfo info;

    main() 
    {

        pCpw cpw;

        cpw = null;

        cpwInitContext( &cpw ); /* create the context and init it */

        cpwCreateWindowEx( cpw, "Tank Wars", 100, 100, 300, 300 );

        memset( &list, 0, sizeof( CpwJoystickList ) );
        memset( &info, 0, sizeof( CpwJoystickInfo ) );

        /* ask for one joystick and setup some custom ranges */

        MCpwJoysticksRequested( list, 1 );

        /* set some custom axis and rotation ranges */
        /* (using helper macros in cpw_macros.h) */

        MCpwJoystickAxisRange( list, 0, 100 );
        MCpwJoystickRotRange( list, 0, 359 );
        MCpwJoystickVelRange( list, 0, 100 );
        MCpwJoystickAccelRange( list, 0, 100 );

        /* init a joystick if one is present */

        if ( !cpwInitJoysticks( cpw, &list ) )
            printf( "No joystick support found.\n" );

        ..
    }

    draw() 
    {

        if ( MCpwJoystick1Id( list ) != 0 ) {

            /* we have a joystick */

            cpwJoystickPoll( cpw, &info );

            xpos = MCpwJoystickXAxis( info );
            ypos = MCpwJoystickYAxis( info );

            rotation = MCpwJoystickZRot( info );

            if ( MCpwJoystickPov( list, 1 ) ) 
            {
                /* we have a POV */

                switch( MCpwJoystickPov1( info ) ) 
                {
                    case CPW_POV_CENTERED:
                    break;
                    case CPW_POV_UP:
                    crosshair_y = crosshair_y + 1;
                    break;
                    case CPW_POV_UPRIGHT:
                    crosshair_x = crosshair_x + .5;
                    crosshair_y = crosshair_y + .5;
                    break;
                    case CPW_POV_RIGHT:
                    crosshair_x = crosshair_x + 1;
                    break;
                    case CPW_POV_DOWNRIGHT:
                    crosshair_x = crosshair_x + .5;
                    crosshair_y = crosshair_y - .5;
                    break;
                    case CPW_POV_DOWN:
                    crosshair_y = crosshair_y - 1;
                    break;
                    case CPW_POV_DOWNLEFT:
                    crosshair_x = crosshair_x + .5;
                    crosshair_y = crosshair_y - .5;
                    break;
                    case CPW_POV_LEFT:
                    crosshair_x = crosshair_x - 1;
                    break;
                    case CPW_POV_UPLEFT:
                    crosshair_x = crosshair_x + .5;
                    crosshair_y = crosshair_y - .5;
                    break;
                }
            }
        }
        ..
    }
Default Ranges:
    CPW_JOY_AXISMIN       -1000
    CPW_JOY_AXISMAX        1000
    CPW_JOY_ROTATIONMIN    0
    CPW_JOY_ROTATIONMAX    3590
    CPW_JOY_VELOCITYMIN    0
    CPW_JOY_VELOCITYMAX    1000
POV position constants:
    CPW_POV_UP
    CPW_POV_UPRIGHT
    CPW_POV_RIGHT
    CPW_POV_DOWNRIGHT
    CPW_POV_DOWN
    CPW_POV_DOWNLEFT
    CPW_POV_LEFT
    CPW_POV_UPLEFT
Joystick structures:
    struct _CpwJoystickList
    {
        uint_8                  joysticks;
        CpwJoystickRanges       ranges;
        CpwJoystickCapabilities caps[CPW_MAX_JOYSTICKS];
    };
    typedef struct _CpwJoystickList CpwJoystickList;

    struct _CpwJoystickCapabilities
    {
        uint_8  id;                     /* the joystick id value */

        bool    axis[CPW_JOY_AXES];     /* x, y, z, u, v axis */
        bool    rot[CPW_JOY_AXES];      /* axis rotation */
        bool    variablepov;            /* point-of-view hats are variable */
        bool    pov[CPW_JOY_POVS];      /* point-of-view hats */
        bool    vel[CPW_JOY_AXES];      /* axis velocity */
        bool    accel[CPW_JOY_AXES];    /* axis acceleration */
        bool    forcefeedback;          /* supports force feedback */
        uint_32 numbuttons;             /* number of buttons supported */
    };
    typedef struct _CpwJoystickCapabilities CpwJoystickCapabilities;

    struct _CpwJoystickRanges
    {
        bool   axis;     /* use custom axis range values */
        int_16 axismin;  /* user definable minimum axis normalization value */
        int_16 axismax;  /* user definable maximum axis normalization value */
        bool   rotation; /* use custom rotation range values */
        int_16 rotmin;   /* user definable minimum rotation normalization value. */
        int_16 rotmax;   /* user definable maximum rotation normalization value. */
        bool   velocity; /* use custom velocity range values */
        int_16 velmin;   /* user definable minimum velocity normalization value */
        int_16 velmax;   /* user definable maximum velocity normalization value */
        bool   accel;    /* use custom accel range values */
        int_16 accelmin; /* user definable minimum acceleration normalization value. */
        int_16 accelmax; /* user definable maximum acceleration normalization value. */
    };
    typedef struct _CpwJoystickRanges CpwJoystickRanges;

    struct _CpwJoystickInfo
    {
        uint_8 id;                       /* the joystick id to access */

        int_32 axis[CPW_JOY_AXES];       /* x, y, z, u, v axis */
        int_32 rot[CPW_JOY_AXES];        /* axis rotation */
        int_32 pov[CPW_JOY_POVS];        /* point-of-view hats, variable or discrete */
        int_32 vel[CPW_JOY_AXES];        /* axis velocity */
        int_32 accel[CPW_JOY_AXES];      /* axis acceleration */
        bool   buttons[CPW_JOY_BUTTONS]; /* button states */
    };
    typedef struct _CpwJoystickInfo CpwJoystickInfo;




2D and 3D Primitive Rendering Library

Utility functions for drawing basic 2D and 3D primitives like box, line, rectangle, filled rectangle, sphere, torus, and teapot.

bool cpwSetPrimitiveOpt( pCpw cpw, uint_32 option, float_32 value )

Sets a particular primitive option value.

Primitve Options:

    CPW_PRIMOPT_RESET,          /* resets primitive drawing state */
    CPW_PRIMOPT_SIZE,
    CPW_PRIMOPT_RADIUS,
    CPW_PRIMOPT_INNERRADIUS,
    CPW_PRIMOPT_OUTERRADIUS,
    CPW_PRIMOPT_TOPRADIUS,
    CPW_PRIMOPT_BASERADIUS,
    CPW_PRIMOPT_WIDTH,
    CPW_PRIMOPT_HEIGHT,
    CPW_PRIMOPT_SLICES,
    CPW_PRIMOPT_STACKS,
    CPW_PRIMOPT_SCALE,
bool cpwDrawPrimitive( pCpw cpw, uint_32 primitive )

Draw a particluar 2d or 3d primitive.

Primitive Constants:

    CPW_PRIM_3D_WIRESPHERE,       /* wire sphere     radius, slices, stacks */
    CPW_PRIM_3D_SOLIDSPHERE,      /* solid sphere    radius, slices, stacks */
    CPW_PRIM_3D_WIRECONE,         /* wire cone       baseradius, topradius, slices, stacks */
    CPW_PRIM_3D_SOLIDCONE,        /* solid cone      baseradius, topradius, slices, stacks */
    CPW_PRIM_3D_WIRECUBE,         /* wire cube       size */
    CPW_PRIM_3D_SOLIDCUBE,        /* solid cube      size */
    CPW_PRIM_3D_WIRETORUS,        /* wire torus      innerradius, outerradius, slices, stacks */
    CPW_PRIM_3D_SOLIDTORUS,       /* solid torus     innerradius, outerradius, slices, stacks */
    CPW_PRIM_3D_WIREDOUGHNUT,     /* wire torus      innerradius, outerradius, slices, stacks */
    CPW_PRIM_3D_SOLIDDOUGHNUT,    /* solid torus     innerradius, outerradius, slices, stacks */
    CPW_PRIM_3D_WIREDISK,         /* wire torus      innerradius, outerradius, slices, stacks */
    CPW_PRIM_3D_SOLIDDISK,        /* solid torus     innerradius, outerradius, slices, stacks */
    CPW_PRIM_3D_WIRETEAPOT,       /* teapot          scale */
    CPW_PRIM_3D_SOLIDTEAPOT,      /* teapot          scale */
    CPW_PRIM_3D_TEAPOTAHEDRON,    /* history         scale */
    CPW_PRIM_2D_RECTANGLE,        /* rectangle       scale */
    CPW_PRIM_2D_FILLEDRECTANGLE,  /* filledrect      scale */
    CPW_PRIM_2D_LINE,             /* line            width */
    CPW_PRIM_2D_SQUARE,           /* rectangle       scale */
    CPW_PRIM_2D_FILLEDSQUARE,     /* filledrect      scale */
    CPW_PRIM_2D_RECTANGLE,        /* rectangle       width, height */
    CPW_PRIM_2D_FILLEDRECTANGLE,  /* filledrect      width, height */




OpenGL Extensions

Utility functions for querying support of and iterating each of the localhost's OpenGL extensions.

pChar cpwIterateExtensions( pCpw cpw )

Iterates each extension supported, returning a null terminated string or null when the end of the list is reached.

bool cpwIterateExtensionsReset( pCpw cpw )

Resets the iteration index for cpwIterateExtensions.

bool cpwExtensionSupport( pCpw cpw, pChar string )

Tests to see if a particluar extension is supported using a string search across the entire extension string list.

Example Use:

    char * p;

    while ( ( p = cpwIterateExtensions( cpw ) ) != 0 ) {
        printf( "Extension '%s' supported.\n", p );
    }

    printf( "\n" );

    cpwIterateExtensionsReset( cpw );

    while ( ( p = cpwIterateExtensions( cpw ) ) != 0 ) {
        printf( "Extension '%s' supported.\n", p );
    }




Performance Timing

Code segments performance tracking. Useful for finding performance bottlenecks in your code.

uint_32 cpwAddMark( pCpw cpw, pChar name, bool average )

Creates a new performace mark. 'average' indicates if the mark's time period is reported as the total time spent within the mark, or if it is reported as the averaged time spent within the mark. Returns a mark id used in subsequent calls to cpwEnterMark and cpwExitMark.

bool cpwEnterMark( pCpw cpw, uint_32 id )

Indicates the execution thread is entering a particular mark.

bool cpwExitMark( pCpw cpw, uint_32 id )

Indicates the execution thread is leaving a particular mark.

void cpwDumpMarks( pCpw cpw )

Dumps performance mark data to the print handler. Does not reset mark data. Time is in seconds.

Example Use:

    m1 = cpwAddMark( cpw, "draw window 1", true );
    m2 = cpwAddMark( cpw, "draw window 2", true );
    m3 = cpwAddMark( cpw, "total time   ", true );

    cpwEnterMark( cpw, m3 );
    cpwMainLoop( cpw );
    cpwExitMark( cpw, m3 );

    cpwDumpMarks( cpw );
Dump marks output:
    Performance Marks:
    ---------------------------------------------
      draw window 1  0.0000298 av.
      draw window 2  0.0253379 av.
      total time     10.3396788 av.




Simple Frame Counter

A simple easy to use frame counter.

void cpwFpsInit( pCpw cpw )

Initializes the simple frame counter.

void cpwFpsDraw( pCpw cpw, bool print )

Increases the frame counter by one. 'print' indicates if the frame rate should be printed to the print handler each second.

uint_32 cpwFpsGet( pCpw cpw )

Returns the current number of frames per second.



Library Constants

int_32 cpwGet( pCpw cpw, uint_32 parameter )

      CPW_INIT_WINDOW_X
      CPW_INIT_WINDOW_Y
      CPW_INIT_WINDOW_WIDTH
      CPW_INIT_WINDOW_HEIGHT
      CPW_INIT_DISPLAY_MODE
      CPW_SCREEN_WIDTH 
      CPW_SCREEN_HEIGHT
      CPW_SCREEN_WIDTH_MM       - for compat, returns 0
      CPW_SCREEN_HEIGHT_MM      - for compat, returns 0
      CPW_WINDOW_X              - for compat, use cpwWindowInfo
      CPW_WINDOW_Y              - for compat, use cpwWindowInfo
      CPW_WINDOW_WIDTH          - for compat, use cpwWindowInfo
      CPW_WINDOW_HEIGHT         - for compat, use cpwWindowInfo
      CPW_WINDOW_FOREGROUND     - returns id of the foreground window
      CPW_WINDOW_GLCURRENT      - returns id of the gl current window
      CPW_WINDOW_COUNT          - total number of open windows
      CPW_MOUSE_BUTTONS         - returns the number of mouse buttons (up to 3)
      CPW_ELAPSED_TIME          - for compat, returns 0
      CPW_DRIVER_VENDOR         - 0 or null terminated string pointer
      CPW_DRIVER_RENDERER       - 0 or null terminated string pointer
      CPW_DRIVER_VERSION        - 0 or null terminated string pointer
      CPW_VERSION               - integer value
      CPW_PLATFORM              - returns the platform id