mirror of
https://github.com/spiffcode/hostile-takeover.git
synced 2025-12-16 12:08:36 +00:00
1035 lines
35 KiB
C
1035 lines
35 KiB
C
/* -*- mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-
|
|
*
|
|
* Copyright (c) 2003 Tapwave, Inc. All rights reserved.
|
|
*
|
|
* All rights reserved. This is private and not for public distribution.
|
|
*/
|
|
#ifndef __TWGFX_H__
|
|
#define __TWGFX_H__
|
|
|
|
#include "TwError.h"
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
/*
|
|
* Constants
|
|
*/
|
|
|
|
/*
|
|
* TwGfx specific error codes
|
|
*/
|
|
#define twGfxErrorLibraryOpen (0 + twGfxErrorBase)
|
|
#define twGfxErrorNullPointer (1 + twGfxErrorBase)
|
|
#define twGfxErrorBadObjectVersion (2 + twGfxErrorBase)
|
|
#define twGfxErrorSurfaceAllocFailed (3 + twGfxErrorBase)
|
|
#define twGfxErrorLibraryClosed (4 + twGfxErrorBase)
|
|
|
|
#define twGfxErrorInvalidAlignment (9 + twGfxErrorBase)
|
|
#define twGfxErrorInvalidHandle (10 + twGfxErrorBase)
|
|
#define twGfxErrorInvalidPixelFormat (11 + twGfxErrorBase)
|
|
#define twGfxErrorInvalidLocation (12 + twGfxErrorBase)
|
|
#define twGfxErrorInvalidSize (13 + twGfxErrorBase)
|
|
#define twGfxErrorInvalidRotation (14 + twGfxErrorBase)
|
|
#define twGfxErrorInvalidMirror (15 + twGfxErrorBase)
|
|
#define twGfxErrorInvalidCount (16 + twGfxErrorBase)
|
|
#define twGfxErrorInvalidSurface (17 + twGfxErrorBase)
|
|
#define twGfxErrorInvalidCoord (18 + twGfxErrorBase)
|
|
#define twGfxErrorInvalidFlags (19 + twGfxErrorBase)
|
|
|
|
#define twGfxErrorSurfaceNotLocked (20 + twGfxErrorBase)
|
|
#define twGfxErrorOperationInProgress (21 + twGfxErrorBase)
|
|
|
|
/* Memory location for surfaces */
|
|
#define twGfxLocationAcceleratorMemory 1
|
|
|
|
/* Pixel formats. Note that most api's support a subset of the formats. */
|
|
#define twGfxPixelFormatMonochrome 0 /* 1 bit per pixel (colormap) */
|
|
#define twGfxPixelFormat1bpp 0 /* 1 bit per pixel (colormap) */
|
|
#define twGfxPixelFormatRGB565 1 /* little endian */
|
|
#define twGfxPixelFormatRGB565_LE 1 /* little endian */
|
|
#define twGfxPixelFormatRGB565_BE 2 /* big endian */
|
|
#define twGfxPixelFormat2bpp 3 /* 2 bits per pixel (colormap) */
|
|
#define twGfxPixelFormat4bpp 4 /* 4 bits per pixel (colormap) */
|
|
#define twGfxPixelFormat8bpp 5 /* 8 bits per pixel (colormap) */
|
|
|
|
/* Rotation for TwGfxTransformBlt */
|
|
#define twGfxRotateNone 0
|
|
#define twGfxRotateCW90 1 /* clockwise 90 degrees */
|
|
#define twGfxRotateCW180 2 /* clockwise 180 degrees */
|
|
#define twGfxRotateCW270 3 /* clockwise 270 degrees */
|
|
#define twGfxRotateCCW90 twGfxRotateCW270 /* counter-clockwise 90 degrees */
|
|
#define twGfxRotateCCW180 twGfxRotateCW180 /* counter-clockwise 180 degrees */
|
|
#define twGfxRotateCCW270 twGfxRotateCW90 /* counter-clockwise 270 degrees */
|
|
|
|
/* Mirror for TwGfxTransformBlt */
|
|
#define twGfxMirrorNone 0
|
|
#define twGfxMirrorHorizontal 1
|
|
#define twGfxMirrorVertical 2
|
|
#define twGfxMirrorBoth 3
|
|
|
|
/***********************************************************************/
|
|
|
|
/*
|
|
* Macro to construct a frame buffer compatible rgb565 color given
|
|
* three 8 bit components. This is a manually optimized version that
|
|
* is consistent with the other color macros here.
|
|
*
|
|
* Note that the 68k version of this macro generates data that is
|
|
* byte-swapped into little-endian format. This means that data passed
|
|
* to TwGfxDrawBitmap and TwGfxWriteSurface will be properly arranged
|
|
* if you use this macro.
|
|
*/
|
|
#define TwGfxMakeDisplayRGB_BigEndian(_r,_g,_b) \
|
|
( (((_g) & 0xFC) << 11) | (((_b) & 0xF8) << 5) | ((_r) & 0xF8) | (((_g) & 0xFF) >> 5) )
|
|
|
|
#define TwGfxMakeDisplayRGB_LittleEndian(_r,_g,_b) \
|
|
( (((_r) & 0xF8) << 8) | (((_g) & 0xFC) << 3) | (((_b) & 0xF8) >> 3) )
|
|
|
|
#if CPU_TYPE == CPU_68K
|
|
#define TwGfxMakeDisplayRGB(_r,_g,_b) TwGfxMakeDisplayRGB_BigEndian(_r,_g,_b)
|
|
#else
|
|
#define TwGfxMakeDisplayRGB(_r,_g,_b) TwGfxMakeDisplayRGB_LittleEndian(_r,_g,_b)
|
|
#endif
|
|
|
|
/*
|
|
* This macro converts a RGBColorType structure to a frame buffer
|
|
* compatible display value.
|
|
*/
|
|
#define TwGfxRGBToDisplayRGB(_rgb) TwGfxMakeDisplayRGB((_rgb).r, (_rgb).g, (_rgb).b)
|
|
|
|
/*
|
|
* These macros take an 8 bit color component and adjust them to be
|
|
* sized to match the rgb565 display framebuffer
|
|
*/
|
|
#define TwGfxRComponentToDisplayComponent(_r) (((_r) & 0xF8) >> 3)
|
|
#define TwGfxGComponentToDisplayComponent(_g) (((_g) & 0xFC) >> 2)
|
|
#define TwGfxBComponentToDisplayComponent(_b) (((_b) & 0xF8) >> 3)
|
|
|
|
/*
|
|
* Format information for the rgb565 display buffer
|
|
*/
|
|
#define twGfxRShift 11
|
|
#define twGfxRMask 0xF800
|
|
#define twGfxGShift 5
|
|
#define twGfxGMask 0x07E0
|
|
#define twGfxBShift 0
|
|
#define twGfxBMask 0x001F
|
|
|
|
/*
|
|
* This macro converts from packed component RGB to packed display RGB
|
|
*/
|
|
#define TwGfxPackedRGBToDisplayRGB(_rgb) \
|
|
( (TwGfxRComponentToDisplayComponent((_rgb) >> 16) << twGfxRShift) | \
|
|
(TwGfxGComponentToDisplayComponent((_rgb) >> 8) << twGfxGShift) | \
|
|
(TwGfxBComponentToDisplayComponent((_rgb)) << twGfxBShift) )
|
|
|
|
/*
|
|
* This macro converts a RGBColorType structure to a
|
|
* TwGfxPackedRGBType value.
|
|
*/
|
|
#define TwGfxRGBToPackedRGB(_rgb) \
|
|
((TwGfxPackedRGBType) ( (((UInt32)(_rgb).r) << 16) | \
|
|
((UInt32)((_rgb).g) << 8) | \
|
|
((UInt32)(_rgb).b) ) )
|
|
|
|
/*
|
|
* This macro converts rgb components to a TwGfxPackedRGBType
|
|
*/
|
|
#define TwGfxComponentsToPackedRGB(_r,_g,_b) \
|
|
((TwGfxPackedRGBType) ( ((((UInt32)(_r)) & 0xFF) << 16) | \
|
|
((((UInt32)(_g)) & 0xFF) << 8) | \
|
|
(((UInt32)(_b)) & 0xFF) ) )
|
|
|
|
/*
|
|
* This macro helps fill in a TwGfxPointType
|
|
*/
|
|
#define TwGfxMakePoint(_point, _x, _y) \
|
|
((_point).x = (_x), (_point).y = (_y))
|
|
|
|
/*
|
|
* This macro helps fill in a TwGfxRectType
|
|
*/
|
|
#define TwGfxMakeRect(_rect, _x, _y, _w, _h) \
|
|
((_rect).x = (_x), (_rect).y = (_y), (_rect).w = (_w), (_rect).h = (_h))
|
|
|
|
/***********************************************************************/
|
|
|
|
/*
|
|
* Opaque structures
|
|
*/
|
|
typedef struct TwGfxTypeTag TwGfxType;
|
|
typedef struct TwGfxSurfaceTypeTag TwGfxSurfaceType;
|
|
|
|
/*
|
|
* Structures
|
|
*/
|
|
|
|
|
|
/*
|
|
* Color information. This is the "abstract" RGB color value. This is
|
|
* not the same as the display pixel format. This type is used for the
|
|
* API entry points. Use the TwGfxComponentsToPackedRGB to construct
|
|
* instances of this type.
|
|
*/
|
|
typedef UInt32 TwGfxPackedRGBType;
|
|
|
|
/*
|
|
* TwGfx library state information structure
|
|
*/
|
|
typedef struct TwGfxInfoTypeTag {
|
|
Int32 size; /* caller MUST set this to sizeof(TwGfxInfoType) */
|
|
|
|
Int32 displayWidth, displayHeight; /* current dimensions of display */
|
|
Int32 displayRowBytes; /* byte width of entire row */
|
|
Int32 displayPixelFormat; /* format of display */
|
|
|
|
Int32 freeAcceleratorMemory; /* free accelerator memory */
|
|
Int32 totalAcceleratorMemory; /* total accelerator memory */
|
|
} TwGfxInfoType;
|
|
|
|
/*
|
|
* Surface information structure
|
|
*/
|
|
typedef struct TwGfxSurfaceInfoTypeTag {
|
|
Int32 size; /* caller MUST set this to sizeof(TwGfxSurfaceInfoType) */
|
|
|
|
Int32 width, height; /* dimensions */
|
|
Int32 rowBytes; /* byte width of entire row */
|
|
|
|
Int32 location; /* which memory the surface is located */
|
|
Int32 pixelFormat; /* format of the surface */
|
|
} TwGfxSurfaceInfoType;
|
|
|
|
/*
|
|
* Bitmap structure
|
|
*/
|
|
typedef struct TwGfxBitmapTypeTag {
|
|
Int32 size; /* caller MUST set this to sizeof(TwGfxBitmapType) */
|
|
|
|
Int32 width, height; /* size of bitmap */
|
|
Int32 rowBytes; /* bytes per row */
|
|
Int32 pixelFormat; /* format of data */
|
|
void* data; /* actual data */
|
|
|
|
UInt16* palette; /* In native display format: twGfxPixelFormatRGB565_LE */
|
|
} TwGfxBitmapType;
|
|
|
|
typedef struct TwGfxPointTypeTag {
|
|
Int32 x, y;
|
|
} TwGfxPointType;
|
|
|
|
typedef struct TwGfxRectTypeTag {
|
|
Int32 x, y, w, h;
|
|
} TwGfxRectType;
|
|
|
|
typedef struct TwGfxSpanTypeTag {
|
|
Int32 x, y, w;
|
|
} TwGfxSpanType;
|
|
|
|
/***********************************************************************/
|
|
|
|
|
|
/*
|
|
* Methods
|
|
*/
|
|
|
|
/*
|
|
* Open access to the graphics library. This must be called at least
|
|
* once. aResult is filled in with an opaque handle to the
|
|
* library. aInfoResult is filled in (if not NULL) with information
|
|
* describing the current state of the display.
|
|
*
|
|
* Note that the display state will be affected by the
|
|
* TwSetOrientationState call as well as the presence/absence/size of
|
|
* the pen input area and the status bar.
|
|
*
|
|
* Errors:
|
|
* twGfxErrorLibraryOpen
|
|
* twGfxErrorBadObjectVersion
|
|
*
|
|
* See also:
|
|
* TwSetOrientationState
|
|
* PINSetInputAreaState
|
|
* StatHide
|
|
* StatShow
|
|
*/
|
|
Err TwGfxOpen(TwGfxType** aResult,
|
|
TwGfxInfoType* aInfoResult)
|
|
TAL_TRAP(trapTwGfxOpen);
|
|
|
|
/*
|
|
* Release an instance of the TwGfx library. This call should be
|
|
* called to free all memory resources associated with the instance.
|
|
* This call will also call TwFreeSurface for all allocated surfaces
|
|
* that have not yet been freed that were allocated using this
|
|
* instance of the library.
|
|
*
|
|
* Errors:
|
|
* twGfxErrorInvalidHandle
|
|
*/
|
|
Err TwGfxClose(TwGfxType* aGfx)
|
|
TAL_TRAP(trapTwGfxClose);
|
|
|
|
/*
|
|
* Query the current state of the TwGfx library. This can be used, for
|
|
* example, to determine how much free memory is available as well as
|
|
* determine the display state.
|
|
*
|
|
* Errors:
|
|
* twGfxErrorInvalidHandle
|
|
* twGfxErrorNullPointer
|
|
* twGfxErrorBadObjectVersion
|
|
*/
|
|
Err TwGfxGetInfo(TwGfxType* aGfx,
|
|
TwGfxInfoType* aResult)
|
|
TAL_TRAP(trapTwGfxGetInfo);
|
|
|
|
/*
|
|
* Query the current usage of a given memory location and return how
|
|
* much of the total memory is allocated. For example, to determine
|
|
* how much memory is available on the graphics accelerator set
|
|
* aLocation to twGfxLocationAcceleratorMemory.
|
|
*
|
|
* Errors:
|
|
* twGfxErrorInvalidHandle
|
|
* twGfxErrorNullPointer
|
|
*/
|
|
Err TwGfxGetMemoryUsage(TwGfxType* aGfx,
|
|
Int32 aLocation,
|
|
Int32* aUsedResult)
|
|
TAL_TRAP(trapTwGfxGetMemoryUsage);
|
|
|
|
/*
|
|
* Return the surface used by the display
|
|
*
|
|
* Errors:
|
|
* twGfxErrorInvalidHandle
|
|
* twGfxErrorNullPointer
|
|
*/
|
|
Err TwGfxGetDisplaySurface(TwGfxType* aGfx,
|
|
TwGfxSurfaceType** aResult)
|
|
TAL_TRAP(trapTwGfxGetDisplaySurface);
|
|
|
|
/*
|
|
* Return the surface used by PalmOS. This will be a surface that
|
|
* represents the subset of the display used by PalmOS.
|
|
*
|
|
* Errors:
|
|
* twGfxErrorInvalidHandle
|
|
* twGfxErrorNullPointer
|
|
*/
|
|
Err TwGfxGetPalmDisplaySurface(TwGfxType* aGfx,
|
|
TwGfxSurfaceType** aResult)
|
|
TAL_TRAP(trapTwGfxGetPalmDisplaySurface);
|
|
|
|
/*
|
|
* See if the display is currently in the vertical blanking
|
|
* period. *aInVBlankResult will be set to true if it is, false
|
|
* otherwise.
|
|
*
|
|
* Errors:
|
|
* twGfxErrorInvalidHandle
|
|
* twGfxErrorNullPointer
|
|
*/
|
|
Err TwGfxInVBlank(TwGfxType* aGfx,
|
|
Boolean* aInVBlankResult)
|
|
TAL_TRAP(trapTwGfxInVBlank);
|
|
|
|
/*
|
|
* Wait until the display is is in the vertical blanking period.
|
|
*
|
|
* Errors:
|
|
* twGfxErrorInvalidHandle
|
|
*/
|
|
Err TwGfxWaitForVBlank(TwGfxType* aGfx)
|
|
TAL_TRAP(trapTwGfxWaitForVBlank);
|
|
|
|
/******************************************/
|
|
|
|
/*
|
|
* Attempt to allocate a surface using the parameters defined in
|
|
* aDescription.
|
|
*
|
|
* The aDescription.size field should be set to sizeof(TwSurfaceInfo).
|
|
*
|
|
* aDescription.width and aDescription.height should be to the desired dimensions.
|
|
*
|
|
* aDescription.pixelFormat should be set to the desired pixel
|
|
* format. The following pixel formats are supported:
|
|
*
|
|
* twGfxPixelFormatRGB565_LE
|
|
*
|
|
* aDescription.location should be set to the choice of memory to allocate from.
|
|
*
|
|
* All other fields of aDescription are ignored. Upon success
|
|
* aDescription will be filled in with exact information describing
|
|
* the surface.
|
|
*
|
|
* Notes:
|
|
*
|
|
* Only surfaces that are allocated in the same format as the display
|
|
* will work. There are no pixel format conversions done by the blt
|
|
* operations.
|
|
*
|
|
* Errors:
|
|
* twGfxErrorInvalidHandle
|
|
* twGfxErrorOutOfMemory
|
|
* twGfxErrorInvalidPixelFormat
|
|
* twGfxErrorInvalidLocation
|
|
* twGfxErrorInvalidSize
|
|
* twGfxErrorBadObjectVersion
|
|
* twGfxErrorSurfaceAllocFailed
|
|
*/
|
|
Err TwGfxAllocSurface(TwGfxType* aGfx,
|
|
TwGfxSurfaceType** aResult,
|
|
TwGfxSurfaceInfoType* aDescription)
|
|
TAL_TRAP(trapTwGfxAllocSurface);
|
|
|
|
/*
|
|
* Release the surface memory. If an operation is pending for the
|
|
* surface, this call will wait until the surface is idle before
|
|
* releasing it.
|
|
*
|
|
* Errors:
|
|
* twGfxErrorInvalidHandle
|
|
* twGfxErrorInvalidSurface
|
|
*/
|
|
Err TwGfxFreeSurface(TwGfxSurfaceType* aSurface)
|
|
TAL_TRAP(trapTwGfxFreeSurface);
|
|
|
|
/*
|
|
* Set the clipping rectangle used when rendering with the given
|
|
* surface. If you pass in a NULL pointer for aClipRect then clipping
|
|
* is disabled for the given surface.
|
|
*
|
|
* The clipping rectangle for a surface applies to the following
|
|
* drawing operations:
|
|
*
|
|
* TwGfxDrawPoints
|
|
* TwGfxDrawColorPoints
|
|
* TwGfxDrawLines
|
|
* TwGfxDrawLineSegments
|
|
* TwGfxDrawRect
|
|
* TwGfxFillRect
|
|
* TwGfxDrawSpans
|
|
*
|
|
* The clipping rectangle for a surface does NOT apply to the following
|
|
* drawing operations:
|
|
*
|
|
* TwGfxWriteSurface
|
|
* TwGfxWriteSurfaceRegion
|
|
*
|
|
* Errors:
|
|
* twGfxErrorInvalidHandle
|
|
*/
|
|
Err TwGfxSetClip(TwGfxSurfaceType* aSurface,
|
|
const TwGfxRectType* aClipRect)
|
|
TAL_TRAP(trapTwGfxSetClip);
|
|
|
|
/*
|
|
* Get the current clipping rectangle for the surface. When clipping
|
|
* is disabled for the surface the fields in aClipRectResult will be
|
|
* zero.
|
|
*
|
|
* Errors:
|
|
* twGfxErrorInvalidHandle
|
|
* twGfxErrorNullPointer
|
|
*/
|
|
Err TwGfxGetClip(TwGfxSurfaceType* aSurface,
|
|
TwGfxRectType* aClipRectResult)
|
|
TAL_TRAP(trapTwGfxGetClip);
|
|
|
|
/*
|
|
* Query the surface information.
|
|
*
|
|
* Errors:
|
|
* twGfxErrorInvalidHandle
|
|
* twGfxErrorNullPointer
|
|
* twGfxErrorBadObjectVersion
|
|
*/
|
|
Err TwGfxGetSurfaceInfo(TwGfxSurfaceType* aSurface,
|
|
TwGfxSurfaceInfoType* aResult)
|
|
TAL_TRAP(trapTwGfxGetSurfaceInfo);
|
|
|
|
/*
|
|
* Lock the surface down, returning a pointer to the surface bitmap
|
|
* data. The caller can then manipulate the data directly. Direct
|
|
* manipulation of the surface data on the internal or external memory
|
|
* will be slow compared to using DMA, but doesn't suffer any of the
|
|
* latency issues that DMA has.
|
|
*
|
|
* The lock call can be nested; there should be a matching unlock for
|
|
* every lock, however. The API only guarantees that the modifications
|
|
* to the surface are valid when the final unlock is peformed.
|
|
*
|
|
* Errors:
|
|
* twGfxErrorInvalidHandle
|
|
* twGfxErrorNullPointer
|
|
*/
|
|
Err TwGfxLockSurface(TwGfxSurfaceType* aSurface, void** aAddressResult)
|
|
TAL_TRAP(trapTwGfxLockSurface);
|
|
|
|
/*
|
|
* Release the lock on the surface. When the lock counter goes to zero
|
|
* the surface will be guaranteed to be updated to either the internal
|
|
* or external memory if aUpdateFlags is true.
|
|
*
|
|
* Errors:
|
|
* twGfxErrorInvalidHandle
|
|
* twGfxErrorSurfaceNotLocked
|
|
*/
|
|
Err TwGfxUnlockSurface(TwGfxSurfaceType* aSurface,
|
|
Boolean aUpdate)
|
|
TAL_TRAP(trapTwGfxUnlockSurface);
|
|
|
|
/*
|
|
* Make a copy of a surface. The surface bitmap data is copied to
|
|
* aDestPixels which must be aligned on a 16 bit boundary. It is the
|
|
* callers responsibility to provide enough valid memory for the
|
|
* copy. If aAsync is true then the copy is made asynchronously. You
|
|
* can invoke TwGfxIsSurfaceReady to see when the operation has
|
|
* completed. It is an error to attempt a second copy operation on a
|
|
* surface while one is pending.
|
|
*
|
|
* Errors:
|
|
* twGfxErrorInvalidHandle
|
|
* twGfxErrorNullPointer
|
|
* twGfxErrorOperationInProgress
|
|
* twGfxErrorInvalidAlignment
|
|
*/
|
|
Err TwGfxReadSurface(TwGfxSurfaceType* aSurface,
|
|
void* aDestPixels,
|
|
Boolean aAsync)
|
|
TAL_TRAP(trapTwGfxReadSurface);
|
|
|
|
/*
|
|
* Make a copy of a subset of a surface. The surface bitmap data is
|
|
* copied to aDestPixels which must be aligned on a 16 bit
|
|
* boundary. It is the callers responsibility to provide enough valid
|
|
* memory for the copy. If aAsync is true then the copy is made
|
|
* asynchronously. You can invoke TwGfxIsSurfaceReady to see when the
|
|
* operation has completed. It is an error to attempt a second copy
|
|
* operation on a surface while one is pending.
|
|
*
|
|
* Errors:
|
|
* twGfxErrorInvalidHandle
|
|
* twGfxErrorNullPointer
|
|
* twGfxErrorOperationInProgress
|
|
* twGfxErrorInvalidAlignment
|
|
*/
|
|
Err TwGfxReadSurfaceRegion(TwGfxSurfaceType* aSurface,
|
|
const TwGfxRectType* aBounds,
|
|
void* aDestPixels,
|
|
UInt32 aDestRowBytes,
|
|
Boolean aAsync)
|
|
TAL_TRAP(trapTwGfxReadSurfaceRegion);
|
|
|
|
/*
|
|
* Copy memory to a surface. The memory is copied to the surface
|
|
* bitmap.
|
|
*
|
|
* Source data is arranged linearly (left to right, top to bottom)
|
|
* with the rowbytes being aDestRect->w * sizeof(pixel).
|
|
*
|
|
* If aAsync is true then the copy is made asynchronously. You can
|
|
* invoke TwGfxIsSurfaceReady to see when the operation has
|
|
* completed. It is an error to attempt a second copy operation on a
|
|
* surface while one is pending.
|
|
*
|
|
* Errors:
|
|
* twGfxErrorInvalidHandle
|
|
* twGfxErrorNullPointer
|
|
* twGfxErrorOperationInProgress
|
|
*/
|
|
Err TwGfxWriteSurface(TwGfxSurfaceType* aSurface,
|
|
const void* aSourcePixels,
|
|
Boolean aAsync)
|
|
TAL_TRAP(trapTwGfxWriteSurface);
|
|
|
|
/*
|
|
* Copy memory to a subset of a surface. The memory is copied to the
|
|
* surface bitmap at aDestPoint.
|
|
*
|
|
* Source data is arranged linearly (left to right, top to bottom)
|
|
* with the rowbytes being specified by aSourceRowBytes. There will be
|
|
* a performance impact if aSourceRowBytes is not the same as
|
|
* aDestRect->w * sizeof(pixel).
|
|
*
|
|
* If aAsync is true then the copy is made asynchronously. You can
|
|
* invoke TwGfxIsSurfaceReady to see when the operation has
|
|
* completed. It is an error to attempt a second copy operation on a
|
|
* surface while one is pending.
|
|
*
|
|
* Errors:
|
|
* twGfxErrorInvalidHandle
|
|
* twGfxErrorNullPointer
|
|
* twGfxErrorOperationInProgress
|
|
*/
|
|
Err TwGfxWriteSurfaceRegion(TwGfxSurfaceType* aSurface,
|
|
const TwGfxRectType* aBounds,
|
|
const void* aSourcePixels,
|
|
UInt32 aSourceRowBytes,
|
|
Boolean aAsync)
|
|
TAL_TRAP(trapTwGfxWriteSurfaceRegion);
|
|
|
|
/*
|
|
* See if a surface is ready for an asynchronous operation. If an
|
|
* operation is in progress with the surface then
|
|
* twGfxErrorOperationInProgress is returned. If no operation is in
|
|
* progress and no other error occurs then zero is returned.
|
|
*
|
|
* Surfaces are busy when:
|
|
*
|
|
* An async TwGfxWriteSurface/TwGfxWriteSurfaceRegion is in progress.
|
|
* An async TwGfxReadSurface/TwGfxReadSurfaceRegion is in progress.
|
|
* An async blt is in progress (TwGfxAsyncBlt).
|
|
*
|
|
* Errors:
|
|
* twGfxErrorInvalidHandle
|
|
* twGfxErrorOperationInProgress
|
|
*/
|
|
Err TwGfxIsSurfaceReady(TwGfxSurfaceType* aSurface)
|
|
TAL_TRAP(trapTwGfxIsSurfaceReady);
|
|
|
|
/******************************************/
|
|
|
|
/*
|
|
* Basic bitblt routine.
|
|
*
|
|
* The source surface will be copied to the destination surface at the
|
|
* destination point using the source rectangle.
|
|
*
|
|
* If the coordinate values address pixels outside the source surface
|
|
* a twGfxErrorInvalidCoord error will be returned. It is ok to access
|
|
* pixels outside the destination surface: clipping will ensure that
|
|
* nothing improper happens.
|
|
*
|
|
* Errors:
|
|
* twGfxErrorInvalidHandle
|
|
* twGfxErrorNullPointer
|
|
* twGfxErrorInvalidCoord
|
|
* twGfxErrorOperationInProgress
|
|
*/
|
|
Err TwGfxBitBlt(TwGfxSurfaceType* aDestSurface,
|
|
const TwGfxPointType* aDestPoint,
|
|
TwGfxSurfaceType* aSourceSurface,
|
|
const TwGfxRectType* aSourceRect)
|
|
TAL_TRAP(trapTwGfxBitBlt);
|
|
|
|
/*
|
|
* Asynchronous bitblt routine. Same idea as TwGfxBitBlt except that
|
|
* the transfer is queued and occurs during the next vertical blanking
|
|
* period that the graphics accelerator is idle. If the graphics
|
|
* accelerator is kept constantly busy then when the bitblt occurs is
|
|
* undefined.
|
|
*
|
|
* If the coordinate values address pixels outside the source surface
|
|
* a twGfxErrorInvalidCoord error will be returned. It is ok to access
|
|
* pixels outside the destination surface: clipping will ensure that
|
|
* nothing improper happens.
|
|
*
|
|
* It is safe to queue the same surface for an async blt multiple
|
|
* times before the next vblank. Once the vblank occurs, the async blt
|
|
* is done and the surface is no longer busy.
|
|
*
|
|
* Errors:
|
|
* twGfxErrorInvalidHandle
|
|
* twGfxErrorNullPointer
|
|
* twGfxErrorInvalidCoord
|
|
* twGfxErrorOperationInProgress
|
|
*/
|
|
Err TwGfxAsyncBlt(TwGfxSurfaceType* aDestSurface,
|
|
const TwGfxPointType* aDestPoint,
|
|
TwGfxSurfaceType* aSourceSurface,
|
|
const TwGfxRectType* aSourceRect)
|
|
TAL_TRAP(trapTwGfxAsyncBlt);
|
|
|
|
/*
|
|
* Transparent bitblt routine.
|
|
*
|
|
* The source surface will be copied to the destination surface at the
|
|
* destination point from the source surface using the source
|
|
* rectangle.
|
|
*
|
|
* Pixels in the source surface whose value matches aTransparentColor
|
|
* will not be copied to the destination surface.
|
|
*
|
|
* If the coordinate values address pixels outside the source surface
|
|
* a twGfxErrorInvalidCoord error will be returned. It is ok to access
|
|
* pixels outside the destination surface: clipping will ensure that
|
|
* nothing improper happens.
|
|
*
|
|
* Errors:
|
|
* twGfxErrorInvalidHandle
|
|
* twGfxErrorNullPointer
|
|
* twGfxErrorInvalidCoord
|
|
* twGfxErrorOperationInProgress
|
|
*/
|
|
Err TwGfxTransparentBlt(TwGfxSurfaceType* aDestSurface,
|
|
const TwGfxPointType* aDestPoint,
|
|
TwGfxSurfaceType* aSourceSurface,
|
|
const TwGfxRectType* aSourceRect,
|
|
TwGfxPackedRGBType aTransparentColor)
|
|
TAL_TRAP(trapTwGfxTransparentBlt);
|
|
|
|
/*
|
|
* Masking bitblt routine.
|
|
*
|
|
* The source surface will be copied to the destination surface at the
|
|
* destination point from the source surface using the source
|
|
* rectangle. The source pixels will be masked using the mask bitmap;
|
|
* one bits in the mask will allow the source surface pixel to draw
|
|
* through to the destination surface while zero bits in the mask will
|
|
* have the source surface pixel ignored.
|
|
*
|
|
* The only acceptable pixel format for the mask bitmap is
|
|
* twGfxPixelFormatMonochrome.
|
|
*
|
|
* If the coordinate values address pixels outside the source surface
|
|
* a twGfxErrorInvalidCoord error will be returned. It is ok to access
|
|
* pixels outside the destination surface: clipping will ensure that
|
|
* nothing improper happens.
|
|
*
|
|
* The width and height of the source mask must equal the width and
|
|
* height of the aSourceRect otherwise a twGfxErrorInvalidSize error
|
|
* will be returned.
|
|
*
|
|
* Errors:
|
|
* twGfxErrorInvalidHandle
|
|
* twGfxErrorNullPointer
|
|
* twGfxErrorInvalidCoord
|
|
* twGfxErrorInvalidSize
|
|
* twGfxErrorInvalidPixelFormat
|
|
* twGfxErrorOperationInProgress
|
|
*/
|
|
Err TwGfxMaskBlt(TwGfxSurfaceType* aDestSurface,
|
|
const TwGfxPointType* aDestPoint,
|
|
TwGfxSurfaceType* aSourceSurface,
|
|
const TwGfxRectType* aSourceRect,
|
|
const TwGfxBitmapType* aMask)
|
|
TAL_TRAP(trapTwGfxMaskBlt);
|
|
|
|
/*
|
|
* Blending bitblt routine.
|
|
*
|
|
* The source surface will be copied to the destination surface at the
|
|
* destination point from the source surface using the source
|
|
* rectangle. The source pixels will be blended with the destination
|
|
* pixels using the aSourceAlpha value.
|
|
*
|
|
* If the coordinate values address pixels outside the source surface
|
|
* a twGfxErrorInvalidCoord error will be returned. It is ok to access
|
|
* pixels outside the destination surface: clipping will ensure that
|
|
* nothing improper happens.
|
|
*
|
|
* Errors:
|
|
* twGfxErrorInvalidHandle
|
|
* twGfxErrorNullPointer
|
|
* twGfxErrorInvalidCoord
|
|
* twGfxErrorOperationInProgress
|
|
*/
|
|
Err TwGfxBlendBlt(TwGfxSurfaceType* aDestSurface,
|
|
const TwGfxPointType* aDestPoint,
|
|
TwGfxSurfaceType* aSourceSurface,
|
|
const TwGfxRectType* aSourceRect,
|
|
TwGfxPackedRGBType aSourceAlpha)
|
|
TAL_TRAP(trapTwGfxBlendBlt);
|
|
|
|
/*
|
|
* Masking blending bitblt routine.
|
|
*
|
|
* The source surface will be copied to the destination surface at the
|
|
* destination point from the source surface using the source
|
|
* rectangle. The source pixels will be blended with the destination
|
|
* pixels using the provided alpha mask bitmap.
|
|
*
|
|
* Alpha values are provided using an index bitmap (for example, 4
|
|
* bits per pixel). A zero value in the index data means no source
|
|
* color is used, while the largest index value indicates all of the
|
|
* color is used. At this time the following index pixel formats are
|
|
* supported:
|
|
*
|
|
* twGfxPixelFormat4bpp
|
|
*
|
|
* If the coordinate values address pixels outside the source surface
|
|
* a twGfxErrorInvalidCoord error will be returned. It is ok to access
|
|
* pixels outside the destination surface: clipping will ensure that
|
|
* nothing improper happens.
|
|
*
|
|
* The width and height of the alpha mask must equal the width and
|
|
* height of the aSourceRect otherwise a twGfxErrorInvalidSize error
|
|
* will be returned.
|
|
*
|
|
* Errors:
|
|
* twGfxErrorInvalidHandle
|
|
* twGfxErrorNullPointer
|
|
* twGfxErrorInvalidCoord
|
|
* twGfxErrorInvalidSize
|
|
* twGfxErrorInvalidPixelFormat
|
|
* twGfxErrorOperationInProgress
|
|
*/
|
|
Err TwGfxMaskBlendBlt(TwGfxSurfaceType* aDestSurface,
|
|
const TwGfxPointType* aDestPoint,
|
|
TwGfxSurfaceType* aSourceSurface,
|
|
const TwGfxRectType* aSourceRect,
|
|
const TwGfxBitmapType* aAlphaMask)
|
|
TAL_TRAP(trapTwGfxMaskBlendBlt);
|
|
|
|
/*
|
|
* Stretching bitblt routine.
|
|
*
|
|
* The source surface will be copied to the destination surface at the
|
|
* destination rectangle from the source surface using the source
|
|
* rectangle.
|
|
*
|
|
* If the coordinate values address pixels outside the source surface
|
|
* a twGfxErrorInvalidCoord error will be returned. It is ok to access
|
|
* pixels outside the destination surface: clipping will ensure that
|
|
* nothing improper happens.
|
|
*
|
|
* Errors:
|
|
* twGfxErrorInvalidHandle
|
|
* twGfxErrorNullPointer
|
|
* twGfxErrorInvalidCoord
|
|
* twGfxErrorOperationInProgress
|
|
*/
|
|
Err TwGfxStretchBlt(TwGfxSurfaceType* aDestSurface,
|
|
const TwGfxRectType* aDestRect,
|
|
TwGfxSurfaceType* aSourceSurface,
|
|
const TwGfxRectType* aSourceRect)
|
|
TAL_TRAP(trapTwGfxStretchBlt);
|
|
|
|
/*
|
|
* Tiling bitblt routine.
|
|
*
|
|
* The source surface will be tiled to the destination surface in the
|
|
* destination rectangle area, using the source alignment point to
|
|
* define a relative origin for the tiling.
|
|
*
|
|
* If the coordinate values address pixels outside the source surface
|
|
* a twGfxErrorInvalidCoord error will be returned. It is ok to access
|
|
* pixels outside the destination surface: clipping will ensure that
|
|
* nothing improper happens.
|
|
*
|
|
* Errors:
|
|
* twGfxErrorInvalidHandle
|
|
* twGfxErrorNullPointer
|
|
* twGfxErrorInvalidCoord
|
|
* twGfxErrorOperationInProgress
|
|
*/
|
|
Err TwGfxTileBlt(TwGfxSurfaceType* aDestSurface,
|
|
const TwGfxRectType* aDestRect,
|
|
TwGfxSurfaceType* aSourceSurface,
|
|
const TwGfxPointType* aSourceAlignmentPoint)
|
|
TAL_TRAP(trapTwGfxTileBlt);
|
|
|
|
/*
|
|
* Transformation bitblt routine. Can rotate (none,90,180,27) and/or
|
|
* mirror (none, horz, vert, both) the source surface during the
|
|
* transfer to the destination surface.
|
|
*
|
|
* The source surface will be copied to the destination surface at the
|
|
* destination point from the source surface using the source
|
|
* rectangle.
|
|
*
|
|
* If the coordinate values address pixels outside the source surface
|
|
* a twGfxErrorInvalidCoord error will be returned. It is ok to access
|
|
* pixels outside the destination surface: clipping will ensure that
|
|
* nothing improper happens.
|
|
*
|
|
* When mixing rotation and mirroring, the mirroring is applied first
|
|
* then the rotation.
|
|
*
|
|
* Assuming the following example source bitmap:
|
|
*
|
|
* 123
|
|
* 456
|
|
*
|
|
* Here are all the combinations of rotations and mirrorings:
|
|
*
|
|
* +----------+--------+--------+--------+--------+
|
|
* + Rot/Mir + None + Horz + Vert + Both +
|
|
* +----------+--------+--------+--------+--------+
|
|
* + + 123 + 321 + 456 + 654 +
|
|
* + None + 456 + 654 + 123 + 321 +
|
|
* + + + + + +
|
|
* +----------+--------+--------+--------+--------+
|
|
* + + 41 + 63 + 14 + 36 +
|
|
* + CW90 + 52 + 52 + 25 + 25 +
|
|
* + + 63 + 41 + 36 + 14 +
|
|
* +----------+--------+--------+--------+--------+
|
|
* + + 654 + 456 + 321 + 123 +
|
|
* + CW180 + 321 + 123 + 654 + 456 +
|
|
* + + + + + +
|
|
* +----------+--------+--------+--------+--------+
|
|
* + + 36 + 14 + 63 + 41 +
|
|
* + CW270 + 25 + 25 + 52 + 52 +
|
|
* + + 14 + 36 + 41 + 63 +
|
|
* +----------+--------+--------+--------+--------+
|
|
*
|
|
* Errors:
|
|
* twGfxErrorInvalidHandle
|
|
* twGfxErrorNullPointer
|
|
* twGfxErrorInvalidCoord
|
|
* twGfxErrorInvalidRotation
|
|
* twGfxErrorInvalidMirror
|
|
* twGfxErrorOperationInProgress
|
|
*/
|
|
Err TwGfxTransformBlt(TwGfxSurfaceType* aDestSurface,
|
|
const TwGfxPointType* aDestPoint,
|
|
TwGfxSurfaceType* aSourceSurface,
|
|
const TwGfxRectType* aSourceRect,
|
|
Int32 aRotationFlags,
|
|
Int32 aMirrorFlags)
|
|
TAL_TRAP(trapTwGfxTransformBlt);
|
|
|
|
/*
|
|
* Draw a set of points with a single color into the surface. This is
|
|
* equivalent to locking the surface and plotting the points, but more
|
|
* efficiently. Invalid coordinates are clipped.
|
|
*
|
|
* Errors:
|
|
* twGfxErrorInvalidHandle
|
|
* twGfxErrorNullPointer
|
|
* twGfxErrorInvalidCount
|
|
* twGfxErrorOperationInProgress
|
|
*/
|
|
Err TwGfxDrawPoints(TwGfxSurfaceType* aDestSurface,
|
|
const TwGfxPointType* aPoints,
|
|
Int32 aNumberOfPoints,
|
|
TwGfxPackedRGBType aColor)
|
|
TAL_TRAP(trapTwGfxDrawPoints);
|
|
|
|
/*
|
|
* Same idea as TwGfxDrawPoints except that each point has a distinct
|
|
* color. Invalid coordinates are clipped.
|
|
*
|
|
* Errors:
|
|
* twGfxErrorInvalidHandle
|
|
* twGfxErrorNullPointer
|
|
* twGfxErrorInvalidCount
|
|
* twGfxErrorOperationInProgress
|
|
*/
|
|
Err TwGfxDrawColorPoints(TwGfxSurfaceType* aDestSurface,
|
|
const TwGfxPointType* aPoints,
|
|
Int32 aNumberOfPoints,
|
|
const TwGfxPackedRGBType* aColors)
|
|
TAL_TRAP(trapTwGfxDrawColorPoints);
|
|
|
|
/* TODO: describe which pixels are rendered */
|
|
/* TODO: the chip can draw stippled lines; does anybody except PalmOS care? */
|
|
|
|
/*
|
|
* Draw one or more connected lines using the given color. There must
|
|
* be 2 or more vertices provided. Lines are clipped to the
|
|
* destination surface.
|
|
*
|
|
* Errors:
|
|
* twGfxErrorInvalidHandle
|
|
* twGfxErrorNullPointer
|
|
* twGfxErrorInvalidCount
|
|
* twGfxErrorOperationInProgress
|
|
*/
|
|
Err TwGfxDrawLines(TwGfxSurfaceType* aDestSurface,
|
|
const TwGfxPointType* aPoints,
|
|
Int32 aNumberOfPoints,
|
|
TwGfxPackedRGBType aColor)
|
|
TAL_TRAP(trapTwGfxDrawLines);
|
|
|
|
/*
|
|
* Draw one or more line segments. There must be 2 or more vertices
|
|
* provided, and the count must be even. Lines are clipped to the
|
|
* destination surface.
|
|
*
|
|
* Errors:
|
|
* twGfxErrorInvalidHandle
|
|
* twGfxErrorNullPointer
|
|
* twGfxErrorInvalidCount
|
|
* twGfxErrorOperationInProgress
|
|
*/
|
|
Err TwGfxDrawLineSegments(TwGfxSurfaceType* aDestSurface,
|
|
const TwGfxPointType* aPoints,
|
|
Int32 aNumberOfPoints,
|
|
TwGfxPackedRGBType aColor)
|
|
TAL_TRAP(trapTwGfxDrawLineSegments);
|
|
|
|
// TODO: describe which pixels are rendered
|
|
/*
|
|
* Draw the outline of a rectangle. The resulting lines are clipped to
|
|
* the destination surface.
|
|
*
|
|
* Errors:
|
|
* twGfxErrorInvalidHandle
|
|
* twGfxErrorNullPointer
|
|
* twGfxErrorOperationInProgress
|
|
*/
|
|
Err TwGfxDrawRect(TwGfxSurfaceType* aDestSurface,
|
|
const TwGfxRectType* aRect,
|
|
TwGfxPackedRGBType aColor)
|
|
TAL_TRAP(trapTwGfxDrawRect);
|
|
|
|
// TODO: describe which pixels are rendered
|
|
/*
|
|
* Fill a rectangle. The rectangle is clipped to the destination
|
|
* surface.
|
|
*
|
|
* Errors:
|
|
* twGfxErrorInvalidHandle
|
|
* twGfxErrorNullPointer
|
|
* twGfxErrorOperationInProgress
|
|
*/
|
|
Err TwGfxFillRect(TwGfxSurfaceType* aDestSurface,
|
|
const TwGfxRectType* aRect,
|
|
TwGfxPackedRGBType aColor)
|
|
TAL_TRAP(trapTwGfxFillRect);
|
|
|
|
// TODO: describe which pixels are rendered
|
|
/*
|
|
* Draw a set of constant colored horizontal spans. This is similar to
|
|
* drawing a set of horizontal lines, but with smaller data overhead
|
|
* and higher efficiency. The spans are clipped to the destination
|
|
* surface.
|
|
*
|
|
* Errors:
|
|
* twGfxErrorInvalidHandle
|
|
* twGfxErrorNullPointer
|
|
* twGfxErrorInvalidCount
|
|
* twGfxErrorOperationInProgress
|
|
*/
|
|
Err TwGfxDrawSpans(TwGfxSurfaceType* aDestSurface,
|
|
const TwGfxSpanType* aSpans,
|
|
Int32 aNumberOfSpans,
|
|
TwGfxPackedRGBType aColor)
|
|
TAL_TRAP(trapTwGfxDrawSpans);
|
|
|
|
// TODO: describe which pixels are rendered
|
|
/*
|
|
* Render a bitmap to the destination surface. The bitmap is clipped
|
|
* to the destination surface.
|
|
*
|
|
* The following pixel formats are supported:
|
|
*
|
|
* twGfxPixelFormatMonochrome
|
|
* twGfxPixelFormatRGB565_LE
|
|
* twGfxPixelFormatRGB565_BE
|
|
*
|
|
* Errors:
|
|
* twGfxErrorInvalidHandle
|
|
* twGfxErrorNullPointer
|
|
* twGfxErrorInvalidPixelFormat
|
|
* twGfxErrorBadObjectVersion
|
|
* twGfxErrorOperationInProgress
|
|
*/
|
|
Err TwGfxDrawBitmap(TwGfxSurfaceType* aDestSurface,
|
|
const TwGfxPointType* aDestPoint,
|
|
const TwGfxBitmapType* aBitmap)
|
|
TAL_TRAP(trapTwGfxDrawBitmap);
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
#endif /* __TWGFX_H__ */
|