The Hardwarie Library

Written by Anders F Björklund.
Copyright ©2000-2002 afb. All Rights Reserved

Table of Contents:

• Header File
• Libraries
• Constants
• Types and Structures
• Utility functions
• Setup functions
• Drawing functions
• C++ wrapper classes
• Code Snippet
• Complete Examples

Frequently Asked Questions

Header File

#include <Hardwarie.h>

Libraries

Classic

• HardwarieLibClassic
• Quickdraw3DRAVELib

Carbon

• HardwarieLibCarbon
• OpenGLLibraryStub

Constants

kHardwarieInvisibleAlpha

an alpha value that means totally invisible

kHardwarieOpaqueAlpha

an alpha value that means fully visible

kHardwarieOriginalScale

means original scale of source (no scaling)

kHardwarieCalculateScale

means calculate scale from destination rect

kHardwarieNoRotation

means original rotation of source (no rotation)

kHardwarieRightRotation

shows that positive rotation angles are clockwise

Types and Structures

HardwarieContextPtr

a private structure that represents a drawing context

HardwarieFramePtr

a private structure that represents an image frame (within a context)

HardwariePointPtr

a single 2D point (horizontal/vertical)

struct HardwariePoint
{
    float   h;
    float   v;
};

HardwarieRectPtr

a rectangle

struct HardwarieRect
{
    float   left;
    float   top;
    float   right;
    float   bottom;
};

HardwarieColorPtr

a color, including alpha value

struct HardwarieColor
{
    float   red;
    float   green;
    float   blue;
    float   alpha;
};

Utility functions

HardwarieSetPoint

Converts a integer point (Point) to a float point

void HardwarieSetPoint(HardwariePoint *point, PointPtr p);

HardwarieSetRect

Converts a integer rect (Rect) to a float rect

void HardwarieSetRect(HardwarieRect *rect, RectPtr r);

HardwarieSetRect

Converts a integer color (RGBColor) to a float color

void HardwarieSetColor(HardwarieColor *color, RGBColorPtr c);

HardwarieCreateGWorldFromPict

Creates a offscreen gworld, and optionally loads and draws a PICT resource

OSErr HardwarieCreateGWorldFromPict( GWorldPtr *newGWorld, Rect *newBounds,
	short pictID, Boolean grayscale );

HardwarieRoundUp

Rounds a integer up to the nearest power of two (1,2,4,8,16,...)

int HardwarieRoundUp(int x);

HardwarieSetMaxTextureSize

Sets the maximum size to use for a texture width/height

void HardwarieSetMaxTextureSize(int size);

HardwarieGetMaxTextureSize

int HardwarieGetMaxTextureSize(void);

HardwarieSetDrawOutlines

Whether to draw an outline rect around each frame (default: false)

void HardwarieSetDrawOutlines(Boolean draw);

HardwarieGetDrawOutlines

Boolean HardwarieGetDrawOutlines(void);

HardwarieGetRenderName

Returns the name of the currently used render routine

StringPtr HardwarieGetRenderName(void);

HardwarieGetEngineName

Returns the name of the currently used render engine

StringPtr HardwarieGetEngineName(void);

HardwarieGetTextureMemoryAvailable

Returns the number of bytes of texture memory (VRAM) available

Size HardwarieGetTextureMemoryAvailable(void);

HardwarieGetTotalTextureMemory

Returns the total amount of texture memory (VRAM) in bytes

Size HardwarieGetTotalTextureMemory(void);

Setup functions

HardwarieInit

Creates a context, given a device and window

OSErr HardwarieInit(
    HardwarieContextPtr  *newContext,
    GDHandle            device,
    CWindowPtr          window,
    RectPtr             bounds,
    Boolean             fullScreen);

HardwarieExit

Disposes of an old context

void HardwarieExit(
    HardwarieContextPtr  *oldContext);

HardwarieLoadFrame

Creates a frame, and loads picture to VRAM

OSErr HardwarieLoadFrame(
    HardwarieFramePtr    *newFrameP,
    HardwarieContextPtr  context,
    GWorldPtr           pictureGWorld,
    RectPtr             pictureRect,
    GWorldPtr           maskGWorld,
    RectPtr             maskRect,
    GWorldPtr           alphaGWorld,
    RectPtr             alphaRect);

HardwarieReloadFrame

Updates the frame's contents in VRAM

OSErr HardwarieReloadFrame(
    HardwarieFramePtr    oldFrameP,
    HardwarieContextPtr  context,
    GWorldPtr           pictureGWorld,
    RectPtr             pictureRect,
    GWorldPtr           maskGWorld,
    RectPtr             maskRect,
    GWorldPtr           alphaGWorld,
    RectPtr             alphaRect);

HardwarieUnloadFrame

Disposes of an old frame, return VRAM used

void HardwarieUnloadFrame(
    HardwarieFramePtr    *oldFrameP);

HardwariePause

Call when put in the background, or accessing menu/dialogs/etc.

void HardwariePause(
    HardwarieContextPtr context );

HardwarieResume

Resumes the rendering after a previous pause call

void HardwarieResume(
    HardwarieContextPtr context );

Drawing functions

HardwarieBegin

Begin rendering a new frame of animation

void HardwarieBegin(
    HardwarieContextPtr context );

HardwarieEnd

Stop rendering, and swap buffers to show frame

void HardwarieEnd(
    HardwarieContextPtr context );

HardwarieClearBackground

Fill the background with a color

void HardwarieClearBackground(
    HardwarieContextPtr  context,
    HardwarieColorPtr    color);

HardwariePutPixel

Draws a single pixel

void HardwariePutPixel(
    HardwarieContextPtr  context,
    HardwariePointPtr    loc,
    HardwarieColorPtr    color);

HardwarieDrawLine

Draws a line

void HardwarieDrawLine(
    HardwarieContextPtr  context,
    HardwariePointPtr    from,
    HardwariePointPtr    to,
    HardwarieColorPtr    color);

HardwariePaintRect

Draws a solid rect filled with a color

void HardwariePaintRect(
    HardwarieContextPtr  context,
    HardwarieRectPtr     rect,
    HardwarieColorPtr  	 color);

HardwarieDrawFrame

Draws a previously loaded frame

void HardwarieDrawFrame(
    HardwarieFramePtr   srcFrameP,
    HardwarieRectPtr    dstRect,
    float               alpha);

HardwarieScaledDrawFrame

Draws a frame with a specified scale factor

void HardwarieScaledDrawFrame(
    HardwarieFramePtr   srcFrameP,
    HardwarieRectPtr    dstRect,
    float               alpha,
    float               horizScale,
    float               vertScale);

HardwarieRotatedDrawFrame

Draws a frame at a specified rotation level

void HardwarieRotatedDrawFrame(
    HardwarieFramePtr   srcFrameP,
    HardwarieRectPtr    dstRect,
    float               alpha,
    float               degreesRotation);

C++ wrapper classes

class THardwarieContext

• THardwarieContext(GDHandle device, CWindowPtr window, RectPtr bounds = NULL, bool fullscreen = false) throw (std::runtime_error);
• ~THardwarieContext()
• void pause();
• void resume();
• void begin();
• void end();
• void clearBackground(HardwarieColorPtr color);
• void putPixel(HardwariePointPtr loc, HardwarieColorPtr color);
• void drawLine(HardwariePointPtr from, HardwariePointPtr to, HardwarieColorPtr color);

class THardwarieFrame

• THardwarieFrame(THardwarieContext &context, GWorldPtr imageGWorld, RectPtr imageRect, GWorldPtr maskGWorld = NULL, RectPtr maskRect = NULL, GWorldPtr alphaGWorld = NULL, RectPtr alphaRect = NULL) throw (std::runtime_error);
• ~THardwarieFrame() throw();
• void reload(THardwarieContext &context, GWorldPtr imageGWorld, RectPtr imageRect, GWorldPtr maskGWorld = NULL, RectPtr maskRect = NULL, GWorldPtr alphaGWorld = NULL, RectPtr alphaRect = NULL) throw (std::runtime_error);
• void draw(HardwarieRectPtr rect, float alpha = kHardwarieOpaqueAlpha);
• void drawScaled(HardwarieRectPtr rect, float alpha = kHardwarieOpaqueAlpha, float horizScale = kHardwarieCalculateScale, float vertScale = kHardwarieCalculateScale);
• void drawRotated(HardwarieRectPtr rect, float alpha = kHardwarieOpaqueAlpha, float degreesRotation = kHardwarieNoRotation);

class THardwariePoint

• THardwariePoint(float h = 0.0f, float v = 0.0f) throw()
• THardwariePoint(Point &p) throw()

class THardwarieRect

• THardwarieRect(float left = 0.0f, float top = 0.0f, float right = 0.0f, float bottom = 0.0f) throw();
• THardwarieRect(Rect &r) throw();

class THardwarieColor

• THardwarieColor(float red = 0.0f, float green = 0.0f, float blue = 0.0f, float alpha = kHardwarieOpaqueAlpha) throw ();
• THardwarieColor(RGBColor &c) throw();

Code Snippet

HardwarieContextPtr         gContext = NULL;
HardwarieFramePtr           gFrame = NULL;

extern WindowPtr            window;
extern GWorldPtr            pictureGWorld;
extern GWorldPtr            maskGWorld;
extern GWorldPtr            alphaGWorld;
extern Rect                 windowRect;
extern Rect                 pictureRect;
extern Rect                 maskRect;
extern Rect                 alphaRect;

{
    OSErr           err;
    HardwarieRect    r;
    HardwarieColor   c;
    
    err = HardwarieInit(&gContext, GetMainDevice(), (CWindowPtr) window, &windowRect, false );
    if (err == noErr)
    {
        err = HardwarieLoadFrame( &gFrame, gContext,
                pictureGWorld, &pictureRect, maskGWorld, &maskRect, alphaGWorld, &alphaRect);
        if (err == noErr)
        {
            {
                HardwarieBegin(gContext);
        
                c.red = 0.0;
                c.green = 0.0;
                c.blue = 0.0;
                c.alpha = 0.0;
                HardwarieClearBackground(gContext,&c);
        
                r.left = (float) (((unsigned) Random()) % (windowRect.right - windowRect.left))
                                    - (pictureRect.right - pictureRect.left);
                r.top = (float) (((unsigned) Random()) % (windowRect.right - windowRect.left))
                                    - (pictureRect.bottom - pictureRect.top);
                r.right = r.left + (pictureRect.right - pictureRect.left);
                r.bottom = r.top + (pictureRect.bottom - pictureRect.top);
                HardwarieDrawFrame(gFrame, &r, kHardwarieOpaqueAlpha );
            
                HardwarieEnd(gContext);
            }
        
            HardwarieUnloadFrame(&gFrame);
        }
        
        HardwarieExit(&gContext);
    }
}

Complete Examples

• HardwareTest
• Simple C Example
• Simple C++ Example

$Id$