RwCreateUserDraw(RwUserDrawType type,
RwUserDrawAlignmentTypes alignment,
RwInt32 x, RwInt32 y, RwInt32 width, RwInt32 height,
RwUserDraw *(*callback)(RwUserDraw *userdraw,
void *camimage, RwRect *rect, void *data));
Description
Creates a user-draw.
Arguments
type Type of user-draw to create.
alignment A bitfield representing an alignment type (or "bitwise or" of alignment types).
x X offset of the user-draw from the alignment point (in viewport space units).
y Y offset of the user-draw from the alignment point (in viewport space units).
width Width of the user-draw (in viewport space units).
height Height of the user-draw (in viewport space units).
callback Pointer to the call-back function that will render the user-draw.
Return Value
A pointer to the new user-draw if successful, and NULL otherwise.
Comments
The type of the user-draw determines whether it is aligned with a clump’s origin (rwCLUMPALIGN), with a clump’s vertex (rwVERTEXALIGN), with a clump’s bounding box in viewport space (rwBBOXALIGN), or a camera’s viewport (rwVPALIGN).
The following alignment flags are supported: rwALIGNTOP, rwALIGNBOTTOM, rwALIGNLEFT and rwALIGNRIGHT. For convenience, two common combinations of these flags, rwALIGNTOPLEFT and rwALIGNBOTTOMRIGHT are also defined.
Assuming that the type of the user-draw is rwVERTEXALIGN, then the interpretations of the different valid values for alignment are as follows:
• 0 The center of the user-draw is aligned with the vertex.
• rwALIGNTOP The midpoint of the top edge of the user-draw rectangle is aligned with the vertex.
• rwALIGNBOTTOM The midpoint of the bottom edge of the user-draw rectangle is aligned with the vertex.
• rwALIGNLEFT The midpoint of the left edge of the user-draw rectangle is aligned with the vertex.
• rwALIGNRIGHT The midpoint of the right edge of the user-draw rectangle is aligned with the vertex.
• rwALIGNTOP | rwALIGNLEFT
The top left corner of the user-draw rectangle is aligned with the vertex.
• rwALIGNTOP | rwALIGNRIGHT
The top right corner of the user-draw rectangle is aligned with the vertex.
• rwALIGNBOTTOM | rwALIGNLEFT
The bottom left corner of the user-draw rectangle is aligned with the vertex.
• rwALIGNBOTTOM | rwALIGNRIGHT
The bottom right corner of the user-draw rectangle is aligned with the vertex.
A user-draw is positioned at an offset (x, y) from the point of alignment and its size is specified by width and height.
User-draw call-backs should be declared as follows:
void
callback(RwUserDraw *userdraw, void *camimage,
RwRect *rect, void *data);
Where the call-back’s arguments are as follows:
userdraw Pointer to the user-draw to be rendered.
camimage The camera’s image buffer as returned by RwGetCameraImage() for the current camera. camimage is device dependent. For more information, see Appendix B.
rect Pointer to a rectangle defining the area of the camera’s image buffer into which the call-back may render. This rectangle is specified in viewport space coordinates, i.e., (0, 0) is the origin of the viewport.
data Pointer to the user data of the user-draw being drawn. This value can be obtained by calling RwGetUserDrawData() with userdraw as an argument. data is passed directly to the call-back function for the convenience of the application developer.
Note that the call-back function is always called after all clumps in the scene have been rendered, i.e., when RwEndCameraUpdate() is called. Therefore user-draw rendering always appear in front of clump rendering. In the case of overlapping user-draws, the order of rendering is not defined.
See Also