Index

C/C++ Functions

dtImageDoOutput

DT_SWORD dtImageDoOutput(DT_DTENGINE engine, const DT_UBYTE* img_m, DT_UWORD img_w, DT_UWORD img_h, DT_SLONG img_pitch, DT_UBYTE img_bits_per_pixel, DT_UBYTE reserved, DT_UBYTE transparency, DT_UBYTE quality, DT_UBYTE alpha_treatment, DT_UBYTE edge_smoothing, const DT_UBYTE background_arr[], const DT_UBYTE channel_ordering_arr[], const DT_UBYTE rr[], const DT_UBYTE gg[], const DT_UBYTE bb[], DT_SLONG x, DT_SLONG y, DT_SLONG w, DT_SLONG h, const DT_TM2X2 transform)

Short Description: Render G, GA, RGB or RGBA bitmap image to Output

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.

Parameters

ParameterDescription

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:

  • 0 = Fully opaque
  • 127 = 50% transparent
  • 255 = Fully transparent

quality

Image rendering quality level.

Supported values:

  • 0 = Low Quality But Fast Rendering
  • 1 = High Quality But Slower Rendering
  • 2 = Very High Quality But Slower Rendering
  • 3 = Very High Quality (More Blur) But Slower Rendering

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

  • 0 = Ignore the 2nd byte in GA images and 4th byte in RGBA images. Assuming that the channels are not reordered using the channel_ordering_arr parameter, this will result in the alpha channel being ignored.
  • 1 = Alpha channel represents transparency. This is true even if the channels are reordered using the channel_ordering_arr parameter.
  • 2 = Alpha channel represents opacity. This is true even even if the channels are reordered using the channel_ordering_arr parameter.

For monochrome images

  • 0 = Bits (pixels) in each byte are ordered left to right; 1 represent black, 0 represent white
  • 1 = Bits (pixels) in each byte are ordered left to right; 1 represent white, 0 represent black
  • 2 = Bits (pixels) in each byte are ordered right to left; 1 represent black, 0 represent white
  • 3 = Bits (pixels) in each byte are ordered right to left; 1 represent white, 0 represent black

edge_smoothing

Edge smoothing algorithm.

Supported values:

  • 0 = Edge smoothing is off
  • 1 = Edge smoothing is on, inward (does not change the image boundary)
  • 2 = Edge smoothing is on, outward (extends the image boundary by a small amount)

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:

  • In RGBA images all 4 bytes are used; these 4 bytes represent the background color of an image.
  • In RGB images the first three bytes are used; these 3 bytes represent the background color of an image. The fourth byte is unused and should be set to 255.
  • In GA images the first two bytes are used; these 2 bytes represent the background color of an image. The last two bytes are unused and should be set to 255.
  • In G images only the first byte is used; this byte represent the background color of an image. The last three bytes are unused and should be set to 255.

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:

  • 0, 1 = G channel's index is 0, A channel's index is 1
  • 1, 0 = G channel's index is 1, A channel's index is 0

Sample values for RGB bitmap images:

  • 0, 1, 2 = R channel's index is 0, G channel's index is 1, B channel's index is 2
  • 2, 1, 0 = R channel's index is 2, G channel's index is 1, B channel's index is 0
  • 1, 2, 0 = R channel's index is 1, G channel's index is 2, B channel's index is 0
  • 0, 2, 2 = R channel's index is 0, G channel's index is 2, B channel's index is 2 (in other words G and B color channels map to the same value)
  • 1, 1, 1 = R channel's index is 1, G channel's index is 1, B channel's index is 1 (in other words all color channels map to the same value, resulting in grayscale output)

Sample values for RGBA bitmap images:

  • 0, 1, 2, 3 = R channel's index is 0, G channel's index is 1, B channel's index is 2, A channel's index is 3
  • 2, 1, 0, 3 = R channel's index is 2, G channel's index is 1, B channel's index is 0, A channel's index is 3
  • 1, 2, 3, 0 = R channel's index is 1, G channel's index is 2, B channel's index is 3, A channel's index is 0
  • 3, 2, 1, 0 = R channel's index is 3, G channel's index is 2, B channel's index is 1, A channel's index is 0

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.

Return Value

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.

Comments

The following table illustrates memory surface formats supported by this function.

Format
(bits-per-pixel)
Subformat Description

8

0

gggggggg
8-bit grayscale surface (RGB averaging mode). Eight bits (1 byte) are used to represent the relative intensities of gray. 256 intensities calculated as g = (0.33333*R + 0.33333*G + 0.33333*B).

8

1

TTTTTTTT
8-bit alpha surface. Eight bits (1 byte) are used to represent transparency. 256 alpha values.

8

2

gggggggg
8-bit grayscale surface (RGB normalized mode). Eight bits (1 byte) are used to represent the relative intensities of gray. 256 intensities calculated as g = (0.21268*R + 0.7151*G + 0.07217*B).

8

3

gggggggg
8-bit grayscale surface (R channel). Eight bits (1 byte) are used to represent the relative intensities of gray. 256 intensities calculated as g = R.

8

4

gggggggg
8-bit grayscale surface (G channel). Eight bits (1 byte) are used to represent the relative intensities of gray. 256 intensities calculated as g = G.

8

5

gggggggg
8-bit grayscale surface (B channel). Eight bits (1 byte) are used to represent the relative intensities of gray. 256 intensities calculated as g = B.

8

10

gggggggg
8-bit grayscale surface (inverted RGB averaging mode). Eight bits (1 byte) are used to represent the relative intensities of gray. 256 intensities calculated as g = 255 - (0.33333*R + 0.33333*G + 0.33333*B).

8

12

gggggggg
8-bit grayscale surface (inverted RGB normalized mode). Eight bits (1 byte) are used to represent the relative intensities of gray. 256 intensities calculated as g = 255 - (0.21268*R + 0.7151*G + 0.07217*B).

8

13

gggggggg
8-bit grayscale surface (inverted R channel). Eight bits (1 byte) are used to represent the relative intensities of gray. 256 intensities calculated as g = 255 - R.

8

14

gggggggg
8-bit grayscale surface (inverted G channel). Eight bits (1 byte) are used to represent the relative intensities of gray. 256 intensities calculated as g = 255 - G.

8

15

gggggggg
8-bit grayscale surface (inverted B channel). Eight bits (1 byte) are used to represent the relative intensities of gray. 256 intensities calculated as g = 255 - B.

16

0

xBBBBBGG GGGRRRRR
16-bit RGB surface (1-5-5-5). Five bits are used for each color component. The first bit is not used. 32768 colors.

16

1

BBBBBBGG GGGRRRRR
16-bit RGB surface (6-5-5). Six bits are used for red; five bits are used for green and blue. 65,536 colors.

16

2

BBBBBGGG GGGRRRRR
16-bit RGB surface (5-6-5). Six bits are used for green; five bits are used for red and blue. 65,536 colors.

16

3

BBBBBGGG GGRRRRRR
16-bit RGB surface (5-5-6). Six bits are used for blue; five bits are used for red and green. 65,536 colors.

16

4

BBBBBGGG GGRRRRRx
16-bit RGB surface (5-5-5-1). Five bits are used for each color component. The last bit is not used. 32768 colors.

16

5

BBBBBxGG GGGRRRRR
16-bit RGB surface (5-1-5-5). Five bits are used for each color component. The bit between red and green component is not used. 32768 colors.

16

6

BBBBBGGG GGxRRRRR
16-bit RGB surface (5-5-1-5). Five bits are used for each color component. The bit between green and blue component is not used. 32768 colors.

24

0

BBBBBBBB GGGGGGGG RRRRRRRR
Standard 24-bit RGB surface. Eight bits (1 byte) are used for each color component. 16,777,216 colors.

32

0

BBBBBBBB GGGGGGGG RRRRRRRR xxxxxxxx
32-bit RGB surface. Eight bits (1 byte) are used for each color component. The last byte is not used. 16,777,216 colors.

32

1

xxxxxxxx BBBBBBBB GGGGGGGG RRRRRRRR
32-bit RGB surface. Eight bits (1 byte) are used for each color component. The first byte is not used. 16,777,216 colors.

Legend:
g = bits used to describe gray
R = bits used to describe red, G = bits used to describe green, B = bits used to describe blue
T = bits used to describe transparency (0=fully opaque, 255=fully transparent)
x = unused bits

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.

 

Index