HOOPS/3dGS I.M. Interface

     << Back      Full Index      Forward >>


New_User_Face_Pattern


Functions

HT_User_Face_Pattern * New_User_Face_Pattern (HT_Rendition *nr, int nrows, int ncols, static unsigned char pixmap, const int nsee)
void Set_User_Face_Pattern (HT_Rendition *nr, HT_User_Face_Pattern *pattern)
void Free_User_Face_Pattern (HT_User_Face_Pattern *pattern)

Function Documentation

HT_User_Face_Pattern * New_User_Face_Pattern HT_Rendition *  nr,
int  nrows,
int  ncols,
static unsigned char  pixmap,
const int  nsee
 

Allocates and creates a new face pattern descriptor structure.

Parameters:
nr - Current rendition. Passed by reference.
nrows - Number of rows in pattern.
ncols - Number of columns in pattern.
pixmap - Array of unsigned characters whose values map out the pattern.
nsee - Pattern transparency flag. See below for details.
Returns:
pattern - Pointer to user pattern descriptor structure. See below for details.

DETAILS

This function allows the user to define a custom face pattern as an arbitrary nrows x ncols binary pixmap (or bitmap). Then, the function HIC_Set_User_Face_Pattern() can be used to set the face pattern attribute to the custom defined pattern.

The pattern is defined by the arguments nrows, ncols, and a character array pixmap of nrows x ncols bytes. Each byte represents one pixel, stored in row-major order (i.e., with the column index varying most rapidly). The effect of each byte only depends on whether it is zero or non-zero. Pixels with byte value zero are associated with the face color, pixels with byte value non-zero are associated with the face contrast color. For example:

     static unsigned char wave[] = {
         _,_,_,_,1,1,1,_,_,_,
         _,_,_,1,_,_,_,1,_,_,
         _,_,1,_,_,_,_,_,1,_,
         1,1,_,_,_,_,_,_,_,1,
         _,_,_,_,_,_,_,_,_,_,
     };

     HT_User_Face_Pattern * wave_pat = HIC_New_User_Face_Pattern (nr, 5, 10, wave, UPAT_NORMAL);

nsee should have one of the symbolic constant values UPAT_NORMAL, UPAT_NO_FACE, UPAT_NO_CONTRAST. In the first case, when pattern is applied to a face, the face color pixels are rendered according to the face color attribute and the face contrast color pixels according to the face contrast color attribute. In the second case, the face color pixels are made transparent and the face contrast color pixels have the face contrast color. In the third case, the face color pixels have the face color, and the face contrast color pixels are made transparent.

The user can specify that the pattern be applied with the row order reversed from that of the stored character array by making the nrows argument negative.

HIC_Free_User_Face_Pattern() releases the memory allocated for a user pattern. This should eventually be used to free any user patterns.

NOTES

User defined face patterns are available only with HOOPS I.M., not in classic HOOPS.

User defined face patterns can also be applied n I.M. as window patterns, using HIC_Set_User_Window_Pattern().

To take advantage of hardware acceleration, the size of the face pattern must be of the form 2^x (such that x <= 32).

See also:
Set_User_Face_Pattern, Free_User_Face_Pattern, New_User_Line_Pattern, Set_Face_Pattern

void Set_User_Face_Pattern HT_Rendition *  nr,
HT_User_Face_Pattern *  pattern
 

Applies a user pattern to a rendition created by HIC_New_Rendition().

Parameters:
nr - Rendition created with HIC_New_Rendition() . Passed by reference.
pattern - Pointer to user pattern descriptor structure returned by HIC_New_User_Pattern()

DETAILS

No additional details. See HIC_New_User_Face_Pattern()

NOTES

To take advantage of hardware acceleration, the size of the face pattern must be of the form 2^x (such that x <= 32).

See also:
New_User_Face_Pattern, Free_User_Face_Pattern, New_User_Line_Pattern, Set_Face_Pattern

void Free_User_Face_Pattern HT_User_Face_Pattern *  pattern  ) 
 

Destroys the pattern and frees the memory associated with a custom line pattern allocated by HIC_New_User_Face_Pattern().

Parameters:
pattern - Pointer to a user face pattern descriptor, returned by HIC_New_User_Face_Pattern.

DETAILS

HIC_Free_User_Face_Pattern() releases the memory allocated for a user pattern. This should eventually be used to free any user patterns.

See also:
New_User_Face_Pattern, Set_User_Face_Pattern, New_User_Line_Pattern, Set_Face_Pattern
Main Index

HOOPS/3dGS I.M. Interface

     << Back      Full Index      Forward >>