NAME

hw - HoverWare, an object-oriented three-dimensional graphics library

OVERVIEW

HoverWare is a middleware library which is intended to make the problem of graphics primitive creation and management more tractable. HoverWare is written to interface with ANSI-C code; despite this, it is object-oriented. In order to enhance portability, all parameters to and return values from HoverWare are encapsulated via typedefs; these typedefs are:

The central datatype of HoverWare is the hwObject. From a C point of view, the hwObject looks like this:

    typedef struct _hwObjectStruct *hwObject;
    struct _hwObjectStruct {
        hwObject    parent;
        const char  *name;
        const char  **props;
        hwObject    (*create)( hwObject template );
        void    (*addref)( hwObject obj );
        void    (*destroy)( hwObject obj );
        void    (*modify)( hwObject obj, const char *prop,
                    hwInt32 type, const void *val );
        hwInt32 (*inquire)( hwObject obj, const char *prop,
                    void **val );
        void    (*draw)( hwObject obj );
    };

There are three publicly visible (but read-only) data items:

There are, in addition, 6 methods, or function pointers, which are defined for a HoverWare object:

Each HoverWare object will have one or more properties which further define the object; these properties may ONLY be set and gotten via the modify and inquire methods. When setting a property to a value, the *type* of the value must be passed in. HoverWare properties can be assigned single values, or may be uniform arrays of values. To describe the type of a property, a type naming scheme has been created. A type name consists of a 32-bit integer divided into two parts: the type tag (4 bits) and the count (24 bits). If the count is zero, the parameter value is a scalar pointer type (hwObjects or strings only). The defined type tags are:

In order to find the size of the array, the HW_GET_COUNT(name) macro is provided. To find the type tag, use the HW_GET_BASE(name) macro. To construct a type name, use the HW_MAKE_TYPE(tag,count) macro. Here are some examples of some values and their corresponding type name:

For convenience, the most common array type names have predeclared names in hw.h:

In addition, the following macros may be used to create more readable modification code:

These type names are passed as the third parameter to the modify method (to tell the object what you're giving it), and returned from the inquire method (to tell you what it is you got from the object).

In the object man pages which describe each class template, a shorthand version of this type naming is used. This shorthand consists of an integer count concatenated with a single-character type from the set 'I', 'B', 'F', 'S', and 'O', corresponding to HW_TYPE_INT, HW_TYPE_BOOL, HW_TYPE_FLOAT, HW_TYPE_STRING, and HW_TYPE_OBJECT, respectively. If the integer count is 0, it represents a scalar value. Here are some example shorthand names with their equivalent full types:

In addition to using C code to create and modify hwObjects, an object file format is defined. See hwParseFile for more details on this file format.

HoverWare implements the following 3D object classes:

In addition, HoverWare implements the following GUI classes and utilities:

For more information on each class, please see the appropriate man page.

Hoverware also provides many utility routines:

USING HOVERWARE

The following is the smallest possible HoverWare program. It doesn't do anything but put up a window and wait for the user to hit return on the console from which it was started:

    /* Include HoverWare type and function definitions */
        #include "hw.h"

    main( int argc, char **argv )
    {
        /* Declare a pointer to the display */
            hwDisplay
        disp;
        /* Declare a pointer to the drawable (window) */
            hwDrawable
        draw;

        /* Initialize HoverWare to the default display */
            hwInit( argc, argv );
            disp = hwDefaultDisplay->create( hwDefaultDisplay, NULL, NULL );
        if( !disp ) exit( 1 );

        /* Choose a double-buffered visual */
            if( !disp->chooseVisual( disp, HW_VIS_DBUFF, 0 ) )   exit( 1 );

        /* Create a simple window */
            draw = disp->createWindow( disp, "Test", 100, 100, 256, 256 );
        if( !draw ) exit( 1 );

        /* Make the window the current context.  This *must* be
             * done before any other Hoverware, such as file
             * parsing, object drawing, etc.
             */
        disp->makeCurrent( disp, draw );

        /* Flush out any rendering commands */
        disp->update( disp );

        /* Wait for the user to hit return */
        (void)getchar();
    }

SEE ALSO

Header files

hw.h, hw_types.h, hw_protos.h, hw_display.h

3D objects

hwBox, hwCamera, hwCone, hwDisc, hwEnviron, hwFile, hwGroup, hwLight, hwMesh, hwOrient, hwPolygon, hwPolyline, hwPolymarker, hwQuads, hwRing, hwSphere, hwSpinner, hwStrip, hwSurfRev, hwSurface, hwSweep, hwText, hwTexture, hwTimer, hwTorus, hwTriangles, hwVertex

GUI objects

hwButton, hwFont, hwGUI, hwGauge, hwImage, hwLabel, hwLayout, hwRowCol, hwToggle

Utility functions

hwBinary, hwDisplay, hwGetError, hwInit, hwLookup, hwMatrix, hwParseFile, hwWriteAscii, TexFont