Index of OpenRM - RM Library


 RMmatrix * rmMatrixNew (void)

 No arguments.

Creates a new RMmatrix matrix, returning a handle to the new object to the caller upon success, or NULL upon failure. Use rmMatrixDelete to free an RMmatrix object. at jogoscasinoonline.eu.

The RMmatrix object is a 4x4 array of floating point values. Applications have two alternative approaches that may be used to set the individual values in the RMmatrix: either by using rmMatrixSetValue()/rmMatrixGetValue(), or through direct C-struct access. Bonus Fara Depunere

The RMmatrix object consists of a single 4x4 array of floating point values. The array is indexed with A[row][column], so that A[3][0] refers to an entry that is in the third row, and zero'th column. That particular entry controls translations along the X axis; in RM, matrix multiplies occur from the left.

The general form of RMmatrices is 

       |  1  0  0  0  |       |  Sx 0  0  0  |
       |  0  1  0  0  |       |  0  Sy 0  0  |
  T =  |  0  0  1  0  |   S = |  0  0  Sz 0  |
       |  Tx Ty Tz 1  |       |  0  0  0  1  |

Where T and S are the translation and scale matrices, respectively.

Access to a specific matrix entity using the C-struct interface would be performed as follows: to access the Tx, or X-axis translation in T above, Tx = matrix->m[3][0], where "matrix" is a handle to the RMmatrix object. The "m" entity is the single matrix struct inside the RMmatrix object.

Access to the same element through the API would be: Tx = rmMatrixGetValue(matrix,3,0).

 librm library source file: rmmatrix.c 

 RMenum rmMatrixCopy (RMmatrix *dst,
	              const RMmatrix *src)

 RMmatrix *dst - a handle to the "copy to" RMmatrix (modified). const RMmatrix *src - a handle to the "copy from" RMmatrix (input).

Copies the contents of one RMmatrix object to another. Returns RM_CHILL upon success, or RM_WHACKED upon failure.

 librm library source file: rmmatrix.c 

 RMenum rmMatrixDelete (RMmatrix *toDelete)

 RMmatrix *toDelete - a handle to an RMmatrix object to delete
    (modified).

Releases resources associated with an RMmatrix object. Returns RM_CHILL upon success, or RM_WHACKED upon failure.

 librm library source file: rmmatrix.c 

 RMenum rmMatrixIdentity (RMmatrix *toModify)

 RMmatrix *toModify - a handle to an RMmatrix object (modified).

This routine will set the RMmatrix "toModify" to contain the Identity matrix. Returns RM_CHILL upon success, or RM_WHACKED upon failure.

 librm library source file: rmmatrix.c 

 RMenum rmMatrixSetValue (RMmatrix *toModify,
		          int row,
			  int col,
			  float newValue)

 RMmatrix *toModify - a handle to an RMmatrix object (modified). int row, col - integer values, treated as indices. Must both be in
    the range 0..3, otherwise an error condition results. float newValue - a floating point value to place into the RMmatrix
    object (input).

Assigns a floating point value (newValue) to a single entry in the 4x4 matrix contained in the RMmatrix object, returning RM_CHILL upon success or RM_WHACKED upon failure.

 librm library source file: rmmatrix.c 

 float rmMatrixGetValue (const RMmatrix *toQuery,
		         int row,
			 int col)

    query (input). int row, col - integer values assumed to be indices into the 4x4
    matrix contained within the RMmatrix object. Must be in the range
    0..3 else an error condition is detected.

Use this routine to obtain the value of a single entry from a 4x4 matrix within an RMmatrix object. Returns the entry at [row][col] from the matrix upon success, otherwise an error message is issued and 0.0 is returned.

 librm library source file: rmmatrix.c 

 RMenum rmMatrixTranspose (const RMmatrix *src,
		           RMmatrix *dst)

 const RMmatrix *src - a handle to an RMmatrix object (input). RMmatrix *dst - a handle to an RMmatrix object (modified).

Transposes the input matrix, copying the results back into the "dst" RMmatrix object. Returns RM_CHILL upon success, otherwise RM_WHACKED is returned.

This routine is written such that "src" and "dst" may be the same RMmatrix object.

 librm library source file: rmmatrix.c 

 RMenum rmMatrixMultiply (const RMmatrix *srcA,
		          const RMmatrix *srcB,
			  RMmatrix *dst)

 const RMmatrix *srcA, *srcB - handles to RMmatrix objects (input). RMmatrix *dst - a handle to an RMmatrix object (modified).

Computes the matrix product srcA * srcB, placing the result into "dst". Returns RM_CHILL upon success, or RM_WHACKED upon failure.

Internally, rmMatrixMultiply is written such that "dst" may be the same RMmatrix object as either srcA or srcB.

 librm library source file: rmmatrix.c 

 RMenum rmMatrixInverse (const RMmatrix *src,
		         RMmatrix *dst)

 const RMmatrix *src - a handle to an RMmatrix object (input). RMmatrix *dst - a handle to an RMmatrix object (result).

Will compute the inverse of the 4x4 matrix "src," placing the result into "dst". Returns RM_CHILL upon success, or RM_WHACKED upon failure.

Matrix inversion is performed using Gaussian elimination using a customized version of SGEFA from the Linpack distribution. If the input matrix is singular, an error is reported with rmWarning(), and RM_WHACKED is returned.

 librm library source file: rmmatrix.c 

 RMenum rmPoint4MatrixTransform (const float *src,
			         const RMmatrix *matrix,
				 float *dst)

 const float *src - a handle to an array of floats of length 4
    (input). const RMmatrix *matrix - a handle to an RMmatrix object. float *dst - a handle to an array of floats of length 4 (ouput).

rmPoint4MatrixTransform is one of a family of routines that perform vector-matrix multiplication. This routine multiplies the vector "src" by the matrix, placing the result into vector "dst." It is assumed that both "src" and "dst" are floating point arrays of length 4. Returns RM_CHILL upon success, or RM_WHACKED upon failure.

This routine is written such that "src" and "dst" may be the same array from the caller's perspective.

This routine implements the following operation: 




| a b c d |
| e f g h |
[s0 s1 s2 s3] * | i j k l | = [d0 d1 d2 d3]
| m n o p |

The "src" vector multiplies the matrix from the left (pre multiplication) such that each element of "dst" is the dot product of "src" with a column from the matrix.

See also rmPointMatrixTransform.

 librm library source file: rmmatrix.c 

 RMenum rmPointMatrixTransform (const RMvertex3D *src,
			        const RMmatrix *matrix,
			        RMvertex3D *dst)

 const RMvertex3D *src - a handle to an RMvertex3D object (input). const RMmatrix *matrix - a handle to an RMmatrix object. RMvertex3D *dst - a handle to an RMvertex3D (ouput).

rmPointMatrixTransform is one of a family of routines that perform vector-matrix multiplication. This routine multiplies the RMvertex3D "src" by the matrix, placing the result into RMvertex3D "dst."

This routine differs from rmPoint4MatrixTransform in that it is assumed that the w-coordinate of both "src" and "dst" is 1.0, and that the resulting w-coordinate is not available to the caller upon return.

Returns RM_CHILL upon success, or RM_WHACKED upon failure.

This routine is written such that "src" and "dst" may be the same array from the caller's perspective.

This routine implements the following operation: 




| a b c d |
| e f g h |
[s0 s1 s2 1] * | i j k l | = [d0 d1 d2 n/a]
| m n o p |

The "src" vector multiplies the matrix from the left (pre multiplication) such that each element of "dst" is the dot product of "src" with a column from the matrix.

See also rmPoint4MatrixTransform.

 librm library source file: rmmatrix.c 

 RMenum rmPrintMatrix (const RMmatrix *toPrint)

 const RMmatrix *toPrint - a handle to an RMmatrix that will be
    printed (input).

Prints the contents of an RMmatrix object using C-printf's. Returns RM_CHILL upon success or RM_WHACKED upon failure.

 librm library source file: rmmatrix.c 

 RMenum rmPointMin (const float *input,
	            int count,
		    int vdims,
		    int stride,
		    RMvertex3D *minReturn)

 const float *input - a handle to an array of floating point values
    (input). int count - an integer value indicating the number of "vertices" that
    will be processed (input). int vdims - an integer value indicating the cardinality, or number of
    dimensions, of each vertex. Should be either 1, 2 or 3 (input). int stride - an integer value specifying the stride length in floats
    from one vertex to the next (input). RMvertex3D *minReturn - a handle to an RMvertex3D object (modified).

Finds the minimum point, or vertex value, from a flat array of floating point values. Upon success, the minimum vertex value is copied into the caller-supplied "minReturn," and RM_CHILL is returned. Otherwise, RM_WHACKED is returned upon failure.

The parameter "vdims" defines the number of coordinates in each vertex. Use a value of 2 to specify two-dimensional vertices (x and y values), or 3 for three-dimensional vertices (x, y and z values). A value of 1 is also acceptable.

The parameter "count" specifies how many such vertices are present in the input array. Note that this routine assumes that "input" is just a flat array of floats, and will be logically interpreted as groups of vertices, each of which consists of "vdims" floats per vertex. The coordinates of each vertex are assumed to be contiguously located.

The parameter "stride" tells how many floating point values to skip from one vertex to the next. If we assume that "input" consists of a flat array of RMvertex3D objects (cast to float * when calling this routine), the best way to compute "stride" is: 

       stride = sizeof(RMvertex3D)/sizeof(float)

The reason for "stride" is because some platforms force padding of C-structures to the nearest 8-byte boundary. Hence, sizeof(RMvertex3D) is not always equal to sizeof(float)*3.

 librm library source file: rmmatrix.c 

 RMenum rmPointMax (const float *input,
	            int count,
		    int vdims,
		    int stride,
		    RMvertex3D *maxReturn)

 const float *input - a handle to an array of floating point values
    (input). int count - an integer value indicating the number of "vertices" that
    will be processed (input). int vdims - an integer value indicating the cardinality, or number of
    dimensions, of each vertex. Should be either 1, 2 or 3 (input). int stride - an integer value specifying the stride length in floats
    from one vertex to the next (input). RMvertex3D *maxReturn - a handle to an RMvertex3D object (modified).

Finds the maximum point, or vertex value, from a flat array of floating point values. Upon success, the maximum vertex value is copied into the caller-supplied "maxReturn," and RM_CHILL is returned. Otherwise, RM_WHACKED is returned upon failure.

The parameter "vdims" defines the number of coordinates in each vertex. Use a value of 2 to specify two-dimensional vertices (x and y values), or 3 for three-dimensional vertices (x, y and z values). A value of 1 is also acceptable.

The parameter "count" specifies how many such vertices are present in the input array. Note that this routine assumes that "input" is just a flat array of floats, and will be logically interpreted as groups of vertices, each of which consists of "vdims" floats per vertex. The coordinates of each vertex are assumed to be contiguously located.

The parameter "stride" tells how many floating point values to skip from one vertex to the next. If we assume that "input" consists of a flat array of RMvertex3D objects (cast to float * when calling this routine), the best way to compute "stride" is: 

       stride = sizeof(RMvertex3D)/sizeof(float)

The reason for "stride" is because some platforms force padding of C-structures to the nearest 8-byte boundary. Hence, sizeof(RMvertex3D) is not always equal to sizeof(float)*3.

 librm library source file: rmmatrix.c 

 RMenum rmPointMinMax (const float *input,
	               int count,
		       int vdims,
		       int stride,
		       RMvertex3D *minReturn,
		       RMvertex3D *maxReturn)

 const float *input - a handle to an array of floating point values
    (input). int count - an integer value indicating the number of "vertices" that
    will be processed (input). int vdims - an integer value indicating the cardinality, or number of
    dimensions, of each vertex. Should be either 1, 2 or 3 (input). int stride - an integer value specifying the stride length in floats
    from one vertex to the next (input). RMvertex3D *minReturn, *maxReturn - handles to RMvertex3D objects
    (modified).

Finds the minimum and maximum points, or vertex values, from a flat array of floating point values. Upon success, the minimum and maximum vertex values are copied into the caller-supplied "minReturn" and "maxReturn," respectively, and RM_CHILL is returned. Otherwise, RM_WHACKED is returned upon failure.

The parameter "vdims" defines the number of coordinates in each vertex. Use a value of 2 to specify two-dimensional vertices (x and y values), or 3 for three-dimensional vertices (x, y and z values). A value of 1 is also acceptable.

The parameter "count" specifies how many such vertices are present in the input array. Note that this routine assumes that "input" is just a flat array of floats, and will be logically interpreted as groups of vertices, each of which consists of "vdims" floats per vertex. The coordinates of each vertex are assumed to be contiguously located.

The parameter "stride" tells how many floating point values to skip from one vertex to the next. If we assume that "input" consists of a flat array of RMvertex3D objects (cast to float * when calling this routine), the best way to compute "stride" is: 

       stride = sizeof(RMvertex3D)/sizeof(float)

The reason for "stride" is because some platforms force padding of C-structures to the nearest 8-byte boundary. Hence, sizeof(RMvertex3D) is not always equal to sizeof(float)*3.

This routine internally calls rmPointMin, followed by rmPointMax.

 librm library source file: rmmatrix.c 

 double rmVertex3DMag (const RMvertex3D *src)

 const RMvertex3D *src - a handle to an RMvertex3D object (input).

Computes the vector magnitude of the input RMvertex3D object (a 3-component vector), returning the result to the caller. If the input is NULL, an error message is reported, and -1.0 is returned.

 librm library source file: rmmatrix.c 

 RMenum rmVertex3DSum (const RMvertex3D *a,
	               const RMvertex3D *b,
		       RMvertex3D *dst)

 const RMvertex3D *a, *b - handles to RMvertex3D objects (input). RMvertex3D *dst - a handle to an RMvertex3D object (result).

Computes the vector sum (a + b), placing the result into "dst". This is computed such that either a or b may be used as the result c. Returns RM_CHILL upon success, or RM_WHACKED upon failure.

 librm library source file: rmmatrix.c 

 RMenum rmVertex3DDiff (const RMvertex3D *a,
	                const RMvertex3D *b,
		        RMvertex3D *dst)

 const RMvertex3D *a, *b - handles to RMvertex3D objects (input). RMvertex3D *dst - a handle to an RMvertex3D object (result).

Computes the vector difference (a - b), placing the result into "dst". This is computed such that either a or b may be used as the result c. Returns RM_CHILL upon success, or RM_WHACKED upon failure.

 librm library source file: rmmatrix.c 

 double rmVertex3DDot (const RMvertex3D *a,
	               const RMvertex3D *b)

 const RMvertex3D *a, *b - handles to RMvertex3D objects (input).

Computes the vector dot product of the input RMvertex3D objects "a" and "b," returning the result. Upon failure, an error message is issued through RMwarning() and 0.0 is returned.

 librm library source file: rmmatrix.c 

 RMenum rmVertex3DCross (RMvertex3D *p,
		         RMvertex3D *r,
			 RMvertex3D *result)

 RMvertex3D *p, *r - handles to RMvertex3D objects (input). RMvertex3D *result - a handle to an RMvertex3D object (result).

Computes the vector cross product of the two input vectors "P" and "R", placing the resulting vector into "result". Returns RM_CHILL upon success or RM_WHACKED upon failure.

This routine is written such that "result" may be the same object as either P or R.

 librm library source file: rmmatrix.c 

 RMenum rmVertex3DNormalize (RMvertex3D *toNormalize)

 RMvertex3D *toNormalize - a handle to the RMvertex3D object
    (modified).

Use this routine to normalize the 3-component vector contained in an RMvertex3D object. Inside this routine, the vector magnitude of the RMvertex3D object is computed. Next, if the magnitude is non-zero, each component of the vector is divided by the magnitude, and RM_CHILL is returned. If the magnitude is zero, RM_WHACKED is returned.

 librm library source file: rmmatrix.c 

 RMenum rmVertex3DMagNormalize (RMvertex3D *toNormalize,
		                double *magReturn)

 RMvertex3D *toNormalize - a handle to an RMvertex3D object
    (modified). double *magReturn - a pointer to a double (result).

Use this routine when you want to normalize a vector, and get the vector magnitude of the unnormalized vector in one call.

A return value of RM_CHILL means that all's well, while a return value of RM_WHACKED means that either one of the input parameters was NULL, or that the input RMvertex3D had a zero-valued vector magnitude.

Upon success, the input RMvertex3D is normalized in-situ, and the vector magnitude (used to normalize the vector) is returned in the caller-supplied memory.

 librm library source file: rmmatrix.c 

 RMenum rmVertex3DMidpoint (const RMvertex3D *a,
		            const RMvertex3D *b,
			    RMvertex3D *dst)

 const RMvertex3D *a,*b - handles to RMvertex3D objects (input). RMvertex3D *dst - a handle to an RMvertex3D object (result).

Computes the midpoint between the two RMvertex3D objects "a" and "b", placing the result into "dst". Returns RM_CHILL upon success, or RM_WHACKED upon failure.

 librm library source file: rmmatrix.c 

 RMenum rmDCFromWC3 (const RMvertex3D *src,
	             RMvertex3D *dst,
		     int nPoints,
		     const RMcamera3D *cam3d,
		     const RMmatrix *model,
		     float viewPort[4],
		     int windowWidth,
		     int windowHeight)

 const RMvertex3D *src - an array of RMvertex3D objects (input). RMvertex3D *dst - an array of RMvertex3D objects (result). int nPoints - an integer value indicating the number of points from
    "src" that will be transformed. RMcamera3D *cam3d - a handle to an RMcamera3D object that specifies
    view geometry (input). RMmatrix *model - an RMmatrix object specifying a model
    transformation in world coordinates (input). This parameter is
    optional, and NULL may be used in place of an RMmatrix object. float viewPort[4] - an array of floating point values (length 4)
    specifying the viewport geometry within the display window. Each
    array value should be in the range 0..1, specifying the viewport
    origin and width/height in NDC coordinates. The array is in the
    following order: xmin, ymin, xmax,ymax. In other words, the
    viewport is specified using two coordinates defining the min/max
    corners of the viewport in NDC space. int windowWidth, windowHeight - integer values specifying the width
    and height in pixels of the display window (input).

Use this routine to compute the device coordinates from world coordinates. RM_CHILL is returned upon success, or RM_WHACKED upon failure.

Each RMvertex3D from "src", of which there are nPoints, is transformed through a derived projection matrix producing window (pixel) coordinates that are placed into "dst." Each dst[i] represents the projected window coordinates of src[i]. The derived projection matrix consists of an optional modeling transformation matrix (model), and a viewing matrix computed from the camera model defined by the input RMcamera3D object.

Note that no window is required, the projected coordinates are computed using the window and viewport dimensions specified by the input, no actual rendering occurs (OpenGL is not involved with this routine).

 librm library source file: rmmatrix.c 

 RMenum rmDCFromWC2 (const RMvertex2D *src,
	             RMvertex2D *dst,
		     int nPoints,
		     const RMcamera2D *cam3d,
		     const RMmatrix *model,
		     float viewPort[4],
		     int windowWidth,
		     int windowHeight)

 const RMvertex2D *src - an array of RMvertex2D objects (input). RMvertex2D *dst - an array of RMvertex2D objects (result). int nPoints - an integer value indicating the number of points from
    "src" that will be transformed. RMcamera2D *cam2d - a handle to an RMcamera2D object that specifies
    view geometry (input). RMmatrix *model - an RMmatrix object specifying a model
    transformation in world coordinates (input). This parameter is
    optional, and NULL may be used in place of an RMmatrix object. float viewPort[4] - an array of floating point values (length 4)
    specifying the viewport geometry within the display window. Each
    array value should be in the range 0..1. The array is in the
    following order: xmin, ymin, xmax,ymax. In other words, the
    viewport is specified using two coordinates defining the min/max
    corners of the viewport in NDC space. int windowWidth, windowHeight - integer values specifying the width
    and height in pixels of the display window (input).

Use this routine to compute the device coordinates from world coordinates. RM_CHILL is returned upon success, or RM_WHACKED upon failure.

Each RMvertex2D from "src", of which there are nPoints, is transformed through a derived projection matrix producing window (pixel) coordinates that are placed into "dst." Each dst[i] represents the projected window coordinates of src[i]. The derived projection matrix consists of an optional modeling transformation matrix (model), and a viewing matrix computed from the camera model defined by the input RMcamera2D object.

Note that no window is required, the projected coordinates are computed using the window and viewport dimensions specified by the input, no actual rendering occurs (OpenGL is not involved with this routine).

 librm library source file: rmmatrix.c