## Functions

The Microsoft® Direct3D® Retained Mode functions are:

- D3DRMColorGetAlpha
- D3DRMColorGetBlue
- D3DRMColorGetGreen
- D3DRMColorGetRed
- D3DRMCreateColorRGB
- D3DRMCreateColorRGBA
- D3DRMFREEFUNCTION
- D3DRMMALLOCFUNCTION
- D3DRMMatrixFromQuaternion
- D3DRMQuaternionFromRotation
- D3DRMQuaternionMultiply
- D3DRMQuaternionSlerp
- D3DRMREALLOCFUNCTION
- D3DRMVectorAdd
- D3DRMVectorCrossProduct
- D3DRMVectorDotProduct
- D3DRMVectorModulus
- D3DRMVectorNormalize
- D3DRMVectorRandom
- D3DRMVectorReflect
- D3DRMVectorRotate
- D3DRMVectorScale
- D3DRMVectorSubtract
- Direct3DRMCreate

###

D3DRMColorGetAlpha

Retrieves the alpha component of a color.

D3DVALUE D3DRMColorGetAlpha(
D3DCOLOR d3drmc
);

##### Parameters

d3drmc
  Color from which the alpha component is retrieved. A value between 0 and 255.

##### Return Values

Returns the alpha value if successful, or zero otherwise.

##### See Also

D3DRMColorGetBlue, D3DRMColorGetGreen, D3DRMColorGetRed

###

D3DRMColorGetBlue

Retrieves the blue component of a color.

D3DVALUE D3DRMColorGetBlue(
D3DCOLOR d3drmc
);

##### Parameters

d3drmc
  Color from which the blue component is retrieved. A value between 0 and 255.

##### Return Values

Returns the blue value if successful, or zero otherwise.

##### See Also

D3DRMColorGetAlpha, D3DRMColorGetGreen, D3DRMColorGetRed

###

D3DRMColorGetGreen

Retrieves the green component of a color.

D3DVALUE D3DRMColorGetGreen(
D3DCOLOR d3drmc
);

##### Parameters

d3drmc
  Color from which the green component is retrieved. A value between 0 and 255.

##### Return Values

Returns the green value if successful, or zero otherwise.

##### See Also

D3DRMColorGetAlpha, D3DRMColorGetBlue, D3DRMColorGetRed

###

D3DRMColorGetRed

Retrieves the red component of a color.

D3DVALUE D3DRMColorGetRed(
D3DCOLOR d3drmc
);

##### Parameters

d3drmc
  Color from which the red component is retrieved.

##### Return Values

Returns the red value if successful, or zero otherwise.

##### See Also

D3DRMColorGetAlpha, D3DRMColorGetBlue, D3DRMColorGetGreen

###

Direct3DRMCreate

Creates an instance of a Direct3DRM object.

HRESULT Direct3DRMCreate(
LPDIRECT3DRM FAR * lplpD3DRM
);

##### Parameters

lplpD3DRM
  Address of a pointer that will be initialized with a valid Direct3DRM pointer if the call succeeds.

##### Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

##### See Also

Direct3DRMObject

###

D3DRMCreateColorRGB

Creates an RGB color from supplied red, green, and blue components.

D3DCOLOR D3DRMCreateColorRGB(
D3DVALUE red,
D3DVALUE green,
D3DVALUE blue
);

##### Parameters

red, green, and blue
  Components of the RGB color.

##### Return Values

Returns the new RGB value if successful, or zero otherwise.

##### See Also

D3DRMCreateColorRGBA

###

D3DRMCreateColorRGBA

Creates an RGBA color from supplied red, green, blue, and alpha components.

D3DCOLOR D3DRMCreateColorRGBA(
D3DVALUE red,
D3DVALUE green,
D3DVALUE blue,
D3DVALUE alpha
);

##### Parameters

red, green, blue, and alpha
  Components of the RGBA color. Values between 0 and 1.

##### Return Values

Returns the new RGBA value if successful, or zero otherwise.

##### See Also

D3DRMCreateColorRGB

###

D3DRMFREEFUNCTION

Frees memory. This function is application-defined.

    typedef VOID (*D3DRMFREEFUNCTION)(LPVOID lpArg);
    typedef D3DRMFREEFUNCTION *LPD3DRMFREEFUNCTION;

##### Parameters

lpArg
  Address of application-defined data.

##### Return Values

No return value.

##### Remarks

Applications might define their own memory-freeing function if the standard C run-time routines do not meet their requirements.

###

D3DRMMALLOCFUNCTION

Allocates memory. This function is application-defined.

    typedef LPVOID (*D3DRMMALLOCFUNCTION)(DWORD dwSize);
    typedef D3DRMMALLOCFUNCTION *LPD3DRMMALLOCFUNCTION;

##### Parameters

dwSize
  Size, in bytes, of the memory that will be allocated.

##### Return Values

Returns the address of the allocated memory if successful, or zero otherwise.

##### Remarks

Applications might define their own memory-allocation function if the standard C run-time routines do not meet their requirements.

###

D3DRMMatrixFromQuaternion

Calculates the matrix for the rotation that a unit quaternion represents.

void D3DRMMatrixFromQuaternion (
D3DRMMATRIX4D mat,
LPD3DRMQUATERNION lpquat
);

##### Parameters

mat
  Address that will contain the calculated matrix when the function returns. (The D3DRMMATRIX4D type is an array.)
lpquat
  Address of the D3DRMQUATERNION structure.

##### Return Values

No return value.

###

D3DRMQuaternionFromRotation

Retrieves a unit quaternion that represents a rotation of a specified number of radians around the given axis.

LPD3DRMQUATERNION D3DRMQuaternionFromRotation(
LPD3DRMQUATERNION lpquat,
LPD3DVECTOR lpv,
D3DVALUE theta
);

##### Parameters

lpquat
  Address of a D3DRMQUATERNION structure that will contain the result of the operation.
lpv
  Address of a D3DVECTOR structure specifying the axis of rotation.
theta
  Number of radians to rotate around the axis specified by the lpv parameter.

##### Return Values

Returns the address of the unit quaternion that was passed as the first parameter if successful, or zero otherwise.

###

D3DRMQuaternionMultiply

Calculates the product of two quaternion structures.

LPD3DRMQUATERNION D3DRMQuaternionMultiply(
LPD3DRMQUATERNION lpq,
LPD3DRMQUATERNION lpa,
LPD3DRMQUATERNION lpb
);

##### Parameters

lpq
  Address of the D3DRMQUATERNION structure that will contain the product of the multiplication.
lpa and lpb
  Addresses of the D3DRMQUATERNION structures that will be multiplied together.

##### Return Values

Returns the address of the quaternion that was passed as the first parameter if successful, or zero otherwise.

###

D3DRMQuaternionSlerp

Interpolates between two quaternion structures, using spherical linear interpolation.

LPD3DRMQUATERNION D3DRMQuaternionSlerp(
LPD3DRMQUATERNION lpq,
LPD3DRMQUATERNION lpa,
LPD3DRMQUATERNION lpb,
D3DVALUE alpha
);

##### Parameters

lpq
  Address of the D3DRMQUATERNION structure that will contain the interpolation.
lpa and lpb
  Addresses of the D3DRMQUATERNION structures that are used as the starting and ending points for the interpolation, respectively.
alpha
  Value between 0 and 1 that specifies how far to interpolate between lpa and lpb.

##### Return Values

Returns the address of the quaternion that was passed as the first parameter if successful, or zero otherwise.

###

D3DRMREALLOCFUNCTION

Reallocates memory. This function is application-defined.

    typedef LPVOID (*D3DRMREALLOCFUNCTION)(LPVOID lpArg,
        DWORD dwSize);
    typedef D3DRMREALLOCFUNCTION *LPD3DRMREALLOCFUNCTION;

##### Parameters

lpArg
  Address of application-defined data.
dwSize
  Size, in bytes, of the reallocated memory.

##### Return Values

Returns an address of the reallocated memory if successful, or zero otherwise.

##### Remarks

Applications may define their own memory-reallocation function if the standard C run-time routines do not meet their requirements.

###

D3DRMVectorAdd

Adds two vectors.

LPD3DVECTOR D3DRMVectorAdd(
LPD3DVECTOR lpd,
LPD3DVECTOR lps1,
LPD3DVECTOR lps2
);

##### Parameters

lpd
  Address of a D3DVECTOR structure that will contain the result of the addition.
lps1 and lps2
  Addresses of the D3DVECTOR structures that will be added together.

##### Return Values

Returns the address of the vector that was passed as the first parameter if successful, or zero otherwise.

###

D3DRMVectorCrossProduct

Calculates the cross product of the two vector arguments.

LPD3DVECTOR D3DRMVectorCrossProduct(
LPD3DVECTOR lpd,
LPD3DVECTOR lps1,
LPD3DVECTOR lps2
);

##### Parameters

lpd
  Address of a D3DVECTOR structure that will contain the result of the cross product.
lps1 and lps2
  Addresses of the D3DVECTOR structures from which the cross product is produced.

##### Return Values

Returns the address of the vector that was passed as the first parameter if successful, or zero otherwise.

###

D3DRMVectorDotProduct

Returns the vector dot product.

D3DVALUE D3DRMVectorDotProduct(
LPD3DVECTOR lps1,
LPD3DVECTOR lps2
);

##### Parameters

lps1 and lps2
  Addresses of the D3DVECTOR structures from which the dot product is produced.

##### Return Values

Returns the result of the dot product if successful, or zero otherwise.

###

D3DRMVectorModulus

Returns the length of a vector according to the following formula:

D3DVALUE D3DRMVectorModulus(
LPD3DVECTOR lpv
);

##### Parameters

lpv
  Address of the D3DVECTOR structure whose length is returned.

##### Return Values

Returns the length of the D3DVECTOR structure if successful, or zero otherwise.

###

D3DRMVectorNormalize

Scales a vector so that its modulus is 1.

LPD3DVECTOR D3DRMVectorNormalize(
LPD3DVECTOR lpv
);

##### Parameters

lpv
  Address of a D3DVECTOR structure that will contain the result of the scaling operation.

##### Return Values

Returns the address of the vector that was passed as the first parameter if successful, or zero if an error occurs. An example of an error is if a zero vector were passed.

###

D3DRMVectorRandom

Returns a random unit vector.

LPD3DVECTOR D3DRMVectorRandom(
LPD3DVECTOR lpd
);

##### Parameters

lpd
  Address of a D3DVECTOR structure that will contain a random unit vector.

##### Return Values

Returns the address of the vector that was passed as the first parameter if successful, or zero otherwise.

###

D3DRMVectorReflect

Reflects a ray about a given normal.

LPD3DVECTOR D3DRMVectorReflect(
LPD3DVECTOR lpd,
LPD3DVECTOR lpRay,
LPD3DVECTOR lpNorm
);

##### Parameters

lpd
  Address of a D3DVECTOR structure that will contain the result of the operation.
lpRay
  Address of a D3DVECTOR structure that will be reflected about a normal.
lpNorm
  Address of a D3DVECTOR structure specifying the normal about which the vector specified in lpRay is reflected.

##### Return Values

Returns the address of the vector that was passed as the first parameter if successful, or zero otherwise.

###

D3DRMVectorRotate

Rotates a vector around a given axis. Returns a normalized vector if successful.

LPD3DVECTOR D3DRMVectorRotate(
LPD3DVECTOR lpr,
LPD3DVECTOR lpv,
LPD3DVECTOR lpaxis,
D3DVALUE theta
);

##### Parameters

lpr
  Address of a D3DVECTOR structure that will contain the normalized result of the operation.
lpv
  Address of a D3DVECTOR structure that will be rotated around the given axis.
lpaxis
  Address of a D3DVECTOR structure that is the axis of rotation.
theta
  The amount of rotation in radians.

##### Return Values

Returns the address of the vector that was passed as the first parameter if successful, or zero otherwise. This vector is normalized.

###

D3DRMVectorScale

Scales a vector uniformly in all three axes.

LPD3DVECTOR D3DRMVectorScale(
LPD3DVECTOR lpd,
LPD3DVECTOR lps,
D3DVALUE factor
);

##### Parameters

lpd
  Address of a D3DVECTOR structure that will contain the result of the operation.
lps
  Address of a D3DVECTOR structure that this function scales.
factor
  Scaling factor. A value of 1 does not change the scaling; a value of 2 doubles it, and so on.

##### Return Values

Returns the address of the vector that was passed as the first parameter if successful, or zero otherwise.

###

D3DRMVectorSubtract

Subtracts two vectors.

LPD3DVECTOR D3DRMVectorSubtract(
LPD3DVECTOR lpd,
LPD3DVECTOR lps1,
LPD3DVECTOR lps2
);

##### Parameters

lpd
  Address of a D3DVECTOR structure that will contain the result of the operation.
lps1
  Address of the D3DVECTOR structure from which lps2 is subtracted.
lps2
  Address of the D3DVECTOR structure that is subtracted from lps1.

##### Return Values

Returns the address of the vector that was passed as the first parameter if successful, or zero otherwise.

© 1997 Microsoft Corporation. All rights reserved. Terms of Use.