µGFX  2.9
version 2.9
GMISC

Detailed Description

Module which contains different features such as array conversions.

Data Structures

struct  MatrixFloat2D
 A matrix for doing 2D graphics using floats. More...
 
struct  MatrixFixed2D
 A matrix for doing 2D graphics using fixed point maths. More...
 

Functions

void gmiscArrayConvert (ArrayDataFormat srcfmt, void *src, ArrayDataFormat dstfmt, void *dst, gMemSize cnt)
 Convert from one array format to another array format. More...
 
float invsqrt (float n)
 Fast inverse square root function (x^-1/2) More...
 
void gmiscMatrixFloat2DApplyToPoints (gPoint *dst, const gPoint *src, const MatrixFloat2D *m, int cnt)
 Apply the matrix to a set of points. More...
 
void gmiscMatrixFloat2DSetIdentity (MatrixFloat2D *m)
 Set the 2D matrix to the identity matrix. More...
 
void gmiscMatrixFloat2DMultiply (MatrixFloat2D *dst, const MatrixFloat2D *src1, const MatrixFloat2D *src2)
 Multiple two 2D matrixes together. More...
 
void gmiscMatrixFloat2DApplyTranslation (MatrixFloat2D *dst, const MatrixFloat2D *src, float tx, float ty)
 Add an x,y translation to a matrix. More...
 
void gmiscMatrixFloat2DApplyScale (MatrixFloat2D *dst, const MatrixFloat2D *src, float sx, float sy)
 Add x,y scaling to a matrix. More...
 
void gmiscMatrixFloat2DApplyShear (MatrixFloat2D *dst, const MatrixFloat2D *src, float sx, float sy)
 Add x,y shear to a matrix. More...
 
void gmiscMatrixFloat2DApplyRotation (MatrixFloat2D *dst, const MatrixFloat2D *src, int angle)
 Add rotation to a matrix. More...
 
void gmiscMatrixFixed2DApplyToPoints (gPoint *dst, const gPoint *src, const MatrixFixed2D *m, int cnt)
 Apply the matrix to a set of points. More...
 
void gmiscMatrixFixed2DSetIdentity (MatrixFixed2D *m)
 Set the 2D matrix to the identity matrix. More...
 
void gmiscMatrixFixed2DMultiply (MatrixFixed2D *dst, const MatrixFixed2D *src1, const MatrixFixed2D *src2)
 Multiple two 2D matrixes together. More...
 
void gmiscMatrixFixed2DApplyTranslation (MatrixFixed2D *dst, const MatrixFixed2D *src, fixed tx, fixed ty)
 Add an x,y translation to a matrix. More...
 
void gmiscMatrixFixed2DApplyScale (MatrixFixed2D *dst, const MatrixFixed2D *src, fixed sx, fixed sy)
 Add x,y scaling to a matrix. More...
 
void gmiscMatrixFixed2DApplyShear (MatrixFixed2D *dst, const MatrixFixed2D *src, fixed sx, fixed sy)
 Add x,y shear to a matrix. More...
 
void gmiscMatrixFixed2DApplyRotation (MatrixFixed2D *dst, const MatrixFixed2D *src, int angle)
 Add rotation to a matrix. More...
 
gBool gmiscHittestPoly (const gPoint *pntarray, unsigned cnt, const gPoint *p)
 Check whether a point is inside or on the edge of a polygon. More...
 
double fsin (int degrees)
 Fast Table Based Trig functions. More...
 
fixed ffsin (int degrees)
 Fast Table Based Trig functions. More...
 
#define FIXED(x)   ((fixed)(x)<<16) /* @< integer to fixed */
 Macros to convert to and from a fixed point. More...
 
#define FSIN(degrees)   sintabledouble[degrees];
 Fast Table Based Trig functions. More...
 
#define FFSIN(degrees)   sintablefixed[degrees];
 Fast Table Based Trig functions. More...
 

GMISC Functionality to be included

#define GMISC_NEED_ARRAYOPS   GFXOFF
 Include array operation functions. More...
 
#define GMISC_NEED_FASTTRIG   GFXOFF
 Include fast floating point trig functions (fsin, fcos) More...
 
#define GMISC_NEED_FIXEDTRIG   GFXOFF
 Include fast fixed point trig functions (ffsin, ffcos) More...
 
#define GMISC_NEED_INVSQRT   GFXOFF
 Include fast inverse square root (x^-1/2) More...
 
#define GMISC_NEED_HITTEST_POLY   GFXOFF
 Include polygon hit test functions. More...
 

GMISC Optional Parameters

#define GMISC_INVSQRT_MIXED_ENDIAN   GFXOFF
 Modifies the invsqrt() function to assume a different integer to floating point endianness. More...
 
#define GMISC_INVSQRT_REAL_SLOW   GFXOFF
 Modifies the invsqrt() function to do things the long slow way. More...
 

Macros

#define gfxSampleFormatIsSigned(fmt)   ((fmt) & 1)
 Is the sample data format a "signed" data format? More...
 
#define gfxSampleFormatBits(fmt)   ((fmt) & ~1)
 How many bits are in the sample data format. More...
 
#define FIXED_PI   FP2FIXED(GFX_PI)
 The famous number pi. More...
 

Typedefs

typedef enum ArrayDataFormat_e ArrayDataFormat
 Sample data formats. More...
 
typedef gI32 fixed
 The type for a fixed point type. More...
 
typedef struct MatrixFloat2D MatrixFloat2D
 A matrix for doing 2D graphics using floats. More...
 
typedef struct MatrixFixed2D MatrixFixed2D
 A matrix for doing 2D graphics using fixed point maths. More...
 

Enumerations

enum  ArrayDataFormat_e
 Sample data formats. More...
 

Function Documentation

◆ ffsin()

fixed ffsin ( int  degrees)

Fast Table Based Trig functions.

Returns
A fixed point in the range -1.0 .. 0.0 .. 1.0
Precondition
Requires GFX_USE_GMISC and GMISC_NEED_FIXEDTRIG
Parameters
[in]degreesThe angle in degrees (not radians)
Note
These functions use degrees rather than radians to describe the angle.
Function Class: Normal API, this function can be invoked by regular system threads.

◆ fsin()

double fsin ( int  degrees)

Fast Table Based Trig functions.

Returns
A double in the range -1.0 .. 0.0 .. 1.0
Precondition
Requires GFX_USE_GMISC and GMISC_NEED_FASTTRIG
Parameters
[in]degreesThe angle in degrees (not radians)
Note
These functions use degrees rather than radians to describe the angle.
Function Class: Normal API, this function can be invoked by regular system threads.

◆ gmiscArrayConvert()

void gmiscArrayConvert ( ArrayDataFormat  srcfmt,
void *  src,
ArrayDataFormat  dstfmt,
void *  dst,
gMemSize  cnt 
)

Convert from one array format to another array format.

Precondition
Requires GFX_USE_GMISC and GMISC_NEED_ARRAYOPS
Parameters
[in]srcfmtThe format of the source array
[in]srcThe source array
[in]dstfmtThe format of the destination array
[in]dstThe dstination array
[in]cntThe number of array elements to convert
Note
Assumes the destination buffer is large enough for the resultant data.
This routine is optimised to perform as fast as possible.
No type checking is performed on the source format. It is assumed to have only valid values eg. ARRAY_DATA_4BITSIGNED will have values 0000 -> 0111 for positive numbers and 1111 -> 1000 for negative numbers Bits 5 -> 8 in the storage byte are treated in an undefined manner.
If srcfmt or dstfmt is an unknown format, this routine does nothing with no warning that something is wrong
Function Class: Normal API, this function can be invoked by regular system threads.

◆ gmiscHittestPoly()

gBool gmiscHittestPoly ( const gPoint pntarray,
unsigned  cnt,
const gPoint p 
)

Check whether a point is inside or on the edge of a polygon.

Precondition
Requires GFX_USE_GMISC and GMISC_NEED_HITTEST_POLY
Note
This function works both with convex and concave polygons
Parameters
[in]pntarrayThe array of points that form the polygon
[in]cntThe number of points in the point array pntarray
[in]pThe point to test
Returns
gTrue if the point p is inside or on the edge of the polygon pntarray, gFalse otherwise.
Function Class: Normal API, this function can be invoked by regular system threads.

◆ gmiscMatrixFixed2DApplyRotation()

void gmiscMatrixFixed2DApplyRotation ( MatrixFixed2D dst,
const MatrixFixed2D src,
int  angle 
)

Add rotation to a matrix.

Precondition
Requires GFX_USE_GMISC and GMISC_NEED_MATRIXFIXED2D and GMISC_NEED_FIXEDTRIG
Parameters
[in]dstThe destination matrix
[in]srcThe source matrix. Can be NULL
[in]angleThe angle to apply in degrees (not radians).
Note
In-place matrix operation is NOT allowed ie. dst != src
If no source matrix is provided, it is equivalent to applying the operation to an identity matrix. It also is a much simpler operation requiring no multiplication.
Function Class: Normal API, this function can be invoked by regular system threads.

◆ gmiscMatrixFixed2DApplyScale()

void gmiscMatrixFixed2DApplyScale ( MatrixFixed2D dst,
const MatrixFixed2D src,
fixed  sx,
fixed  sy 
)

Add x,y scaling to a matrix.

Precondition
Requires GFX_USE_GMISC and GMISC_NEED_MATRIXFIXED2D
Parameters
[in]dstThe destination matrix
[in]srcThe source matrix. Can be NULL
[in]sx,syThe scaling to apply in the x and y direction. Negative numbers give reflection.
Note
In-place matrix operation is NOT allowed ie. dst != src
If no source matrix is provided, it is equivalent to applying the operation to an identity matrix. It also is a much simpler operation requiring no multiplication.
Function Class: Normal API, this function can be invoked by regular system threads.

◆ gmiscMatrixFixed2DApplyShear()

void gmiscMatrixFixed2DApplyShear ( MatrixFixed2D dst,
const MatrixFixed2D src,
fixed  sx,
fixed  sy 
)

Add x,y shear to a matrix.

Precondition
Requires GFX_USE_GMISC and GMISC_NEED_MATRIXFIXED2D
Parameters
[in]dstThe destination matrix
[in]srcThe source matrix. Can be NULL
[in]sx,syThe shear to apply in the x and y direction.
Note
In-place matrix operation is NOT allowed ie. dst != src
If no source matrix is provided, it is equivalent to applying the operation to an identity matrix. It also is a much simpler operation requiring no multiplication.
Function Class: Normal API, this function can be invoked by regular system threads.

◆ gmiscMatrixFixed2DApplyToPoints()

void gmiscMatrixFixed2DApplyToPoints ( gPoint dst,
const gPoint src,
const MatrixFixed2D m,
int  cnt 
)

Apply the matrix to a set of points.

Precondition
Requires GFX_USE_GMISC and GMISC_NEED_MATRIXFIXED2D
Parameters
[in]dstThe destination array of points
[in]srcThe source array of points
[in]mThe matrix to apply
[in]cntHow many points are in the array
Note
In-place matrix application is allowed ie. dst = src
Function Class: Normal API, this function can be invoked by regular system threads.

◆ gmiscMatrixFixed2DApplyTranslation()

void gmiscMatrixFixed2DApplyTranslation ( MatrixFixed2D dst,
const MatrixFixed2D src,
fixed  tx,
fixed  ty 
)

Add an x,y translation to a matrix.

Precondition
Requires GFX_USE_GMISC and GMISC_NEED_MATRIXFIXED2D
Parameters
[in]dstThe destination matrix
[in]srcThe source matrix. Can be NULL
[in]tx,tyThe x and y translation to apply
Note
In-place matrix operation is NOT allowed ie. dst != src
If no source matrix is provided, it is equivalent to applying the operation to an identity matrix. It also is a much simpler operation requiring no multiplication.
Function Class: Normal API, this function can be invoked by regular system threads.

◆ gmiscMatrixFixed2DMultiply()

void gmiscMatrixFixed2DMultiply ( MatrixFixed2D dst,
const MatrixFixed2D src1,
const MatrixFixed2D src2 
)

Multiple two 2D matrixes together.

Precondition
Requires GFX_USE_GMISC and GMISC_NEED_MATRIXFIXED2D
Parameters
[in]dstThe destination matrix
[in]src1The first source matrix
[in]src2The second source matrix
Note
In-place matrix application is NOT allowed ie. dst != src1, dst != src2
Function Class: Normal API, this function can be invoked by regular system threads.

◆ gmiscMatrixFixed2DSetIdentity()

void gmiscMatrixFixed2DSetIdentity ( MatrixFixed2D m)

Set the 2D matrix to the identity matrix.

Precondition
Requires GFX_USE_GMISC and GMISC_NEED_MATRIXFIXED2D
Parameters
[in]mThe matrix to set to identity
Function Class: Normal API, this function can be invoked by regular system threads.

◆ gmiscMatrixFloat2DApplyRotation()

void gmiscMatrixFloat2DApplyRotation ( MatrixFloat2D dst,
const MatrixFloat2D src,
int  angle 
)

Add rotation to a matrix.

Precondition
Requires GFX_USE_GMISC and GMISC_NEED_MATRIXFLOAT2D
Parameters
[in]dstThe destination matrix
[in]srcThe source matrix. Can be NULL
[in]angleThe angle to apply in degrees (not radians).
Note
In-place matrix operation is NOT allowed ie. dst != src
If no source matrix is provided, it is equivalent to applying the operation to an identity matrix. It also is a much simpler operation.
If GMISC_NEED_FASTTRIG is defined then the fast table sin and cos lookup's will be used rather than the C library versions.
Function Class: Normal API, this function can be invoked by regular system threads.

◆ gmiscMatrixFloat2DApplyScale()

void gmiscMatrixFloat2DApplyScale ( MatrixFloat2D dst,
const MatrixFloat2D src,
float  sx,
float  sy 
)

Add x,y scaling to a matrix.

Precondition
Requires GFX_USE_GMISC and GMISC_NEED_MATRIXFLOAT2D
Parameters
[in]dstThe destination matrix
[in]srcThe source matrix. Can be NULL
[in]sx,syThe scaling to apply in the x and y direction. Negative numbers give reflection.
Note
In-place matrix operation is NOT allowed ie. dst != src
If no source matrix is provided, it is equivalent to applying the operation to an identity matrix. It also is a much simpler operation requiring no multiplication.
Function Class: Normal API, this function can be invoked by regular system threads.

◆ gmiscMatrixFloat2DApplyShear()

void gmiscMatrixFloat2DApplyShear ( MatrixFloat2D dst,
const MatrixFloat2D src,
float  sx,
float  sy 
)

Add x,y shear to a matrix.

Precondition
Requires GFX_USE_GMISC and GMISC_NEED_MATRIXFLOAT2D
Parameters
[in]dstThe destination matrix
[in]srcThe source matrix. Can be NULL
[in]sx,syThe shear to apply in the x and y direction.
Note
In-place matrix operation is NOT allowed ie. dst != src
If no source matrix is provided, it is equivalent to applying the operation to an identity matrix. It also is a much simpler operation requiring no multiplication.
Function Class: Normal API, this function can be invoked by regular system threads.

◆ gmiscMatrixFloat2DApplyToPoints()

void gmiscMatrixFloat2DApplyToPoints ( gPoint dst,
const gPoint src,
const MatrixFloat2D m,
int  cnt 
)

Apply the matrix to a set of points.

Precondition
Requires GFX_USE_GMISC and GMISC_NEED_MATRIXFLOAT2D
Parameters
[in]dstThe destination array of points
[in]srcThe source array of points
[in]mThe matrix to apply
[in]cntHow many points are in the array
Note
In-place matrix application is allowed ie. dst = src
Function Class: Normal API, this function can be invoked by regular system threads.

◆ gmiscMatrixFloat2DApplyTranslation()

void gmiscMatrixFloat2DApplyTranslation ( MatrixFloat2D dst,
const MatrixFloat2D src,
float  tx,
float  ty 
)

Add an x,y translation to a matrix.

Precondition
Requires GFX_USE_GMISC and GMISC_NEED_MATRIXFLOAT2D
Parameters
[in]dstThe destination matrix
[in]srcThe source matrix. Can be NULL
[in]tx,tyThe x and y translation to apply
Note
In-place matrix operation is NOT allowed ie. dst != src
If no source matrix is provided, it is equivalent to applying the operation to an identity matrix. It also is a much simpler operation requiring no multiplication.
Function Class: Normal API, this function can be invoked by regular system threads.

◆ gmiscMatrixFloat2DMultiply()

void gmiscMatrixFloat2DMultiply ( MatrixFloat2D dst,
const MatrixFloat2D src1,
const MatrixFloat2D src2 
)

Multiple two 2D matrixes together.

Precondition
Requires GFX_USE_GMISC and GMISC_NEED_MATRIXFLOAT2D
Parameters
[in]dstThe destination matrix
[in]src1The first source matrix
[in]src2The second source matrix
Note
In-place matrix application is NOT allowed ie. dst != src1, dst != src2
Function Class: Normal API, this function can be invoked by regular system threads.

◆ gmiscMatrixFloat2DSetIdentity()

void gmiscMatrixFloat2DSetIdentity ( MatrixFloat2D m)

Set the 2D matrix to the identity matrix.

Precondition
Requires GFX_USE_GMISC and GMISC_NEED_MATRIXFLOAT2D
Parameters
[in]mThe matrix to set to identity
Function Class: Normal API, this function can be invoked by regular system threads.

◆ invsqrt()

float invsqrt ( float  n)

Fast inverse square root function (x^-1/2)

Returns
The approximate inverse square root
Precondition
Requires GFX_USE_GMISC and GMISC_NEED_INVSQRT
Parameters
[in]nThe number to find the inverse square root of
Note
This function generates an approximate result. Higher accuracy (at the expense of speed) can be obtained by modifying the source code (the necessary line is already there - just commented out).
This function relies on the internal machine format of a float and a long. If your machine architecture is very unusual this function may not work.
Function Class: Normal API, this function can be invoked by regular system threads.

Macro Definition Documentation

◆ FFSIN

#define FFSIN (   degrees)    sintablefixed[degrees];

Fast Table Based Trig functions.

Returns
A fixed point in the range -1.0 .. 0.0 .. 1.0
Precondition
Requires GFX_USE_GMISC and GMISC_NEED_FIXEDTRIG
Parameters
[in]degreesThe angle in degrees 0 .. 359
Note
These functions use degrees rather than radians to describe the angle.
These functions are super fast but require the parameter to be in range. Use the lowercase functions if the parameter may not be in range or if a required trig function is not supported in this form.
Function Class: Normal API, this function can be invoked by regular system threads.

Definition at line 204 of file gmisc.h.

◆ FIXED

#define FIXED (   x)    ((fixed)(x)<<16) /* @< integer to fixed */

Macros to convert to and from a fixed point.

Definition at line 66 of file gmisc.h.

◆ FIXED_PI

#define FIXED_PI   FP2FIXED(GFX_PI)

The famous number pi.

pi as a fixed point

Definition at line 85 of file gmisc.h.

◆ FSIN

#define FSIN (   degrees)    sintabledouble[degrees];

Fast Table Based Trig functions.

Returns
A double in the range -1.0 .. 0.0 .. 1.0
Precondition
Requires GFX_USE_GMISC and GMISC_NEED_FASTTRIG
Parameters
[in]degreesThe angle in degrees 0 .. 359
Note
These functions use degrees rather than radians to describe the angle.
These functions are super fast but require the parameter to be in range. Use the lowercase functions if the parameter may not be in range or if a required trig function is not supported in this form.
Function Class: Normal API, this function can be invoked by regular system threads.

Definition at line 167 of file gmisc.h.

◆ gfxSampleFormatBits

#define gfxSampleFormatBits (   fmt)    ((fmt) & ~1)

How many bits are in the sample data format.

Definition at line 54 of file gmisc.h.

◆ gfxSampleFormatIsSigned

#define gfxSampleFormatIsSigned (   fmt)    ((fmt) & 1)

Is the sample data format a "signed" data format?

Definition at line 49 of file gmisc.h.

◆ GMISC_INVSQRT_MIXED_ENDIAN

#define GMISC_INVSQRT_MIXED_ENDIAN   GFXOFF

Modifies the invsqrt() function to assume a different integer to floating point endianness.

Note
Normally the floating point format and the integer format have the same endianness. Unfortunately there are some strange processors that don't eg. some very early ARM devices. For those where the endianness doesn't match you can fix it by defining GMISC_INVSQRT_MIXED_ENDIAN.
This still assumes the processor is using an ieee floating point format.

If you have a software floating point that uses a non-standard floating point format (or very strange hardware) then define GMISC_INVSQRT_REAL_SLOW and it will do it the hard way.

Definition at line 78 of file gmisc_options.h.

◆ GMISC_INVSQRT_REAL_SLOW

#define GMISC_INVSQRT_REAL_SLOW   GFXOFF

Modifies the invsqrt() function to do things the long slow way.

Note
This causes the invsqrt() function to work regardless of the processor floating point format.
This makes the invsqrt() function very slow.

Definition at line 87 of file gmisc_options.h.

◆ GMISC_NEED_ARRAYOPS

#define GMISC_NEED_ARRAYOPS   GFXOFF

Include array operation functions.

Defaults to GFXOFF

Definition at line 28 of file gmisc_options.h.

◆ GMISC_NEED_FASTTRIG

#define GMISC_NEED_FASTTRIG   GFXOFF

Include fast floating point trig functions (fsin, fcos)

Defaults to GFXOFF

Definition at line 35 of file gmisc_options.h.

◆ GMISC_NEED_FIXEDTRIG

#define GMISC_NEED_FIXEDTRIG   GFXOFF

Include fast fixed point trig functions (ffsin, ffcos)

Defaults to GFXOFF

Definition at line 42 of file gmisc_options.h.

◆ GMISC_NEED_HITTEST_POLY

#define GMISC_NEED_HITTEST_POLY   GFXOFF

Include polygon hit test functions.

Defaults to GFXOFF

Definition at line 56 of file gmisc_options.h.

◆ GMISC_NEED_INVSQRT

#define GMISC_NEED_INVSQRT   GFXOFF

Include fast inverse square root (x^-1/2)

Defaults to GFXOFF

Definition at line 49 of file gmisc_options.h.

Typedef Documentation

◆ ArrayDataFormat

Sample data formats.

Note
These are defined regardless of whether you use the GMISC module or not as they are used in lots of places.

◆ fixed

typedef gI32 fixed

The type for a fixed point type.

The top 16 bits are the integer component, the bottom 16 bits are the real component.

Definition at line 60 of file gmisc.h.

◆ MatrixFixed2D

typedef struct MatrixFixed2D MatrixFixed2D

A matrix for doing 2D graphics using fixed point maths.

Precondition
Requires GFX_USE_GMISC and GMISC_NEED_MATRIXFIXED2D

◆ MatrixFloat2D

typedef struct MatrixFloat2D MatrixFloat2D

A matrix for doing 2D graphics using floats.

Precondition
Requires GFX_USE_GMISC and GMISC_NEED_MATRIXFLOAT2D

Enumeration Type Documentation

◆ ArrayDataFormat_e

Sample data formats.

Note
These are defined regardless of whether you use the GMISC module or not as they are used in lots of places.

Definition at line 36 of file gmisc.h.