This function draws a bitmap image (i.e. a picture created by a pattern of pixels) within a holding rectangle whose left corner is at coordinates (X, Y) of the current Output. The image's holding rectangle can have any width and height (which does not need to equal the width and height of the bitmap image itself) and can be additionally transformed using a 2x2 transformation matrix.
Bitmap images can be used to represent photographs, icons, complex graphics etc. This function supports bitmap images in RGBA (32 bits per pixel), RGB (24 bits per pixel), GA (16 bits per pixel), G (8 bits per pixel) and monochrome (1 bit per pixel) format, and can process various image format variations. Also, this function supports a number of rendering parameters, such as the quality level, edge smoothing, transparency, duotone output etc.
This functions works only if the Output is connected to a supported Memory Surface (MDC or Memory Device Context) by calling the dtOutputSetAsMDC function. The list of memory surfaces supported by this function is listed below.
Parameter | Description |
---|---|
engine |
Handle of the previously created Standard Engine instance. |
img_m |
Pointer to memory where bitmap image data is stored. The length of the bitmap image data in memory must be img_pitch * img_h bytes. |
img_w |
The width of the bitmap image in pixels. |
img_h |
The height of the bitmap image in pixels. |
img_pitch |
The distance, in bytes, between the beginning of two neighbouring pixel rows. This parameter makes it possible to render bitmap images that have some padding (extra bytes) at the end of each bitmap row. This parameter works with G, GA, RGB and RGBA images but not with monochrome images. Monochrome images must not have any padding. A valid pitch value must be at least img_w * bytes_per_pixel bytes, where bytes_per_pixel is 1 for G, 2 for GA, 3 for RGB and 4 for RGBA images. A pitch value that is exactly img_w * bytes_per_pixel bytes indicates that the pixel rows are contiguous; in other words there are no extra bytes between the neighbouring pixel rows. A pitch value that is larger than img_w * bytes_per_pixel bytes indicates that the pixel rows are non contiguous; in other words at the end of each row there are some extra bytes (the number of extra bytes is img_pitch - img_w * bytes_per_pixel). Note that D-Type Engine does not read or use these extra bytes. A pitch value that is smaller than img_w * bytes_per_pixel is not valid and will be interpreted as img_w * bytes_per_pixel instead. One exception to the above rule is the value 0. Passing img_pitch as 0 is valid and has the same effect as passing img_w * bytes_per_pixel for the same parameter, i.e. it is a simple and convenient way to indicate that the pixel rows are contiguous. |
img_bits_per_pixel |
Format of the bitmap image, i.e. how many bits are used for each pixel. Must be 1 for monochrome, 8 for G, 16 for GA, 24 for RGB and 32 for RGBA images. |
reserved |
Reserved for future use. Must be 0. |
transparency |
Image transparency. The value 0 means minimum intensity, 255 means maximum intensity. Note that this transparency does not replace but is in addition to any per-pixel transparency that may be defined in bitmap images with an alpha channel (i.e. GA and RGBA images). Sample values:
|
quality |
Image rendering quality level. Supported values:
|
alpha_treatment |
For images that contain an alpha channel (GA and RGBA), this is the interpretation of the image's alpha channel. For monochrome images this is the interpretation of the bits (pixels) in each byte. Supported values: For GA and RGBA images
For monochrome images
|
edge_smoothing |
Edge smoothing algorithm. Supported values:
Edge smoothing can be enabled to improve the appearance of the pixels at the very edges of bitmap images that are rotated or skewed using the transform 2x2 transformation matrix. For other situations (i.e. when images are simply scaled) it is best to set edge_smoothing to 0 as this can improve the rendering speed. |
background_arr |
Background color bytes when edge smoothing is enabled. This array has 4 bytes. This array is respected only when edge smoothing is enabled, as follows:
Note that the channel_ordering_arr parameter described below affects the bytes in this array the same way as the bytes of the image itself. If edge smoothing is not enabled, background_arr can be set to DV_NULL. |
channel_ordering_arr |
An array that specifies the order of the bytes (color channels) in each pixel in the bitmap image. This works with all supported bitmap image formats that have at least 2 bytes (color channels) per pixel, making it possible to render bitmap images in which individual pixels are stored using a pattern of GA, RGB or RGBA bytes in any order. The number of elements in the array must equal bytes_per_pixel, where bytes_per_pixel = img_bits_per_pixel / 8. The value of each element is the index of the corresponding color channel in each pixel and must not be smaller than 0 or greater than bytes_per_pixel - 1. It the value of some of the channel_ordering_arr elements is out of range, D-Type Engine will use the modulo bytes_per_pixel arithmetic to index the channels. If the color channels are defined in the standard order, channel_ordering_arr can be set to DV_NULL. Sample values for GA bitmap images:
Sample values for RGB bitmap images:
Sample values for RGBA bitmap images:
|
rr |
An array consisting of exactly 2 elements representing the initial and final intensity of red. This array can be used to render monochrome and grayscale images as duotone. If duotone output is not desired, or if rendering RGB(A) images, this pointer can be set to DV_NULL. |
gg |
An array consisting of exactly 2 elements representing the initial and final intensity of green. This array can be used to render monochrome and grayscale images as duotone. If duotone output is not desired, or if rendering RGB(A) images, this pointer can be set to DV_NULL. |
bb |
An array consisting of exactly 2 elements representing the initial and final intensity of blue. This array can be used to render monochrome and grayscale images as duotone. If duotone output is not desired, or if rendering RGB(A) images, this pointer can be set to DV_NULL. |
x |
X coordinate of the image's holding rectangle, in pixels. |
y |
Y coordinate of the image's holding rectangle, in pixels. |
w |
Width of the image's holding rectangle, in pixels. Must be positive. |
h |
Height of the image's holding rectangle, in pixels. Must be positive. |
transform |
An additional transformation matrix to apply when rendering the image, as defined by DT_TM2X2. The origin of the transformation is at (x, y). If transform is set to DV_NULL, no additional transformation is applied during rendering. |
If the image was successfully drawn, the return value is 1. If the image was not drawn because the Output holds an unsupported memory surface, the function returns -1. In case of some other error, the function returns 0.
The following table illustrates memory surface formats supported by this function.
Format (bits-per-pixel) | Subformat | Description |
---|---|---|
8 | 0 |
gggggggg |
8 | 1 |
TTTTTTTT |
8 | 2 |
gggggggg |
8 | 3 |
gggggggg |
8 | 4 |
gggggggg |
8 | 5 |
gggggggg |
8 | 10 |
gggggggg |
8 | 12 |
gggggggg |
8 | 13 |
gggggggg |
8 | 14 |
gggggggg |
8 | 15 |
gggggggg |
16 | 0 |
xBBBBBGG GGGRRRRR |
16 | 1 |
BBBBBBGG GGGRRRRR |
16 | 2 |
BBBBBGGG GGGRRRRR |
16 | 3 |
BBBBBGGG GGRRRRRR |
16 | 4 |
BBBBBGGG GGRRRRRx |
16 | 5 |
BBBBBxGG GGGRRRRR |
16 | 6 |
BBBBBGGG GGxRRRRR |
24 | 0 |
BBBBBBBB GGGGGGGG RRRRRRRR |
32 | 0 |
BBBBBBBB GGGGGGGG RRRRRRRR xxxxxxxx |
32 | 1 |
xxxxxxxx BBBBBBBB GGGGGGGG RRRRRRRR |
Legend: Note 1: RGB and alpha values are stored only for pixels that are actually rendered by D-Type. Your application must ensure that the surface is cleared with appropriate values before rendering. |