xil_dithermask_get_by_name(3)

NAME

xil_dithermask_get_by_name, xil_dithermask_get_name, xil_dithermask_set_name − get and set a dither mask object name and get the handle of a dither mask

SYNOPSIS

#include <xil/xil.h>

XilDitherMask xil_dithermask_get_by_name (XilSystemState State,

char ∗name);

char∗ xil_dithermask_get_name (XilDitherMask dithermask);

void xil_dithermask_set_name (XilDitherMask dithermask,

char ∗name);

DESCRIPTION

Use these functions to assign names to dither mask objects, to retrieve dither mask objects by name, and to read the names of dither masks. For example, some predefined dither masks are created by an xil_open(3) call. These dither masks can be retrieved by xil_dithermask_get_by_name().

xil_dithermask_get_by_name() returns the handle to the dither mask with the specified name name. If such a dither mask does not exist, NULL is returned. xil_dithermask_get_by_name() does not make a copy of the dither mask.

xil_dithermask_get_name() returns a copy of the specified dither mask’s name. A call to free (3) should be used to free the space allocated by xil_dithermask_get_name(). If the specified dither mask has no name, NULL is returned.

xil_dithermask_set_name() sets the name of the specified dither mask to the one provided.

Standard Dither Masks Provided

The XIL library creates several predefined dither masks at the time of an xil_open(3) call. The names of these dither masks and their suggested uses follow.

Dither Mask Name Suggested Use

"dm883" 8x8x3 mask for dithering 24-bit color images to 8-bit pseudocolor images

"dm881" 8x8x1 mask for dithering 8-bit grayscale images to 1-bit images

"dm443" 4x4x3 mask for dithering 24-bit color images to 8-bit pseudocolor images

"dm441" 4x4x1 mask for dithering 8-bit grayscale images to 1-bit images

ERRORS

For a complete list of XIL error messages by number, consult Appendix B of the XIL Programmer’s Guide.

EXAMPLES

Create and name a 2x2 single-banded dither mask:

XilSystemState State;
XilDitherMask dithermask;
float data[] ={ 0.0, 0.75,
0.25, 0.5 };
xil_dithermask_create(State, 2, 2, 1, data);
xil_dithermask_set_name(dithermask, "small_mask");

Perform a dither operation on a 1-banded image using "small_mask":

XilSystemState State;
XilDitherMask dithermask;
XilLookup cc_2color_bit;/∗ 2-entry cube; black /white ∗/
XilImage byte_image, bit_image;
dithermask = xil_dithermask_get_by_name(State, "small_mask");
xil_ordered_dither(byte_image, bit_image, cc_2color_bit, dithermask);

NOTES

The set of standard objects is generated for each instantiation of an XilSystemState. If these standard objects are deleted, they become unavailable for the duration of the current XIL session.

If you give two dither masks the same name, it is not defined which dither mask will be retrieved by a call to xil_dithermask_get_by_name().

Museum

Related Articles