Screen blit types

Updated: April 19, 2023

Types of blit attributes

Synopsis:

#include <screen/screen.h>
enum {
    SCREEN_BLIT_END = 0,
    SCREEN_BLIT_SOURCE_X = 1,
    SCREEN_BLIT_SOURCE_Y = 2,
    SCREEN_BLIT_SOURCE_WIDTH = 3,
    SCREEN_BLIT_SOURCE_HEIGHT = 4,
    SCREEN_BLIT_DESTINATION_X = 5,
    SCREEN_BLIT_DESTINATION_Y = 6,
    SCREEN_BLIT_DESTINATION_WIDTH = 7,
    SCREEN_BLIT_DESTINATION_HEIGHT = 8,
    SCREEN_BLIT_GLOBAL_ALPHA = 9,
    SCREEN_BLIT_TRANSPARENCY = 10,
    SCREEN_BLIT_SCALE_QUALITY = 11,
    SCREEN_BLIT_COLOR = 12,
    SCREEN_BLIT_ROTATION = 13
};

Data:

SCREEN_BLIT_END
Used to terminate the token-value pairs in an attribute list.
SCREEN_BLIT_SOURCE_X
The horizontal position of the rectangle in the source buffer.

The offset is the distance, in pixels, from the left edge of the source buffer. If this attribute isn't specified, then a default of 0 is used.

SCREEN_BLIT_SOURCE_Y
The vertical position of the rectangle in the source buffer.

The offset is the distance, in pixels, from the top edge of the source buffer. If this attribute isn't specified, then a default of 0 is used.

SCREEN_BLIT_SOURCE_WIDTH
The width, in pixels, of the rectangle in the source buffer.

If this attribute isn't specified, then the source buffer width is used. The horizontal and vertical scale factors don't have to be equal. It's acceptable to specify a source width that's larger than the destination width while the source height is smaller than the destination height, and vice versa.

SCREEN_BLIT_SOURCE_HEIGHT
The height, in pixels, of the rectangle in the source buffer.

If this attribute isn't specified, then the source buffer height is used. The horizontal and vertical scale factors don't have to be equal. It is acceptable to specify a source width that is larger than the destination width while the source height is smaller than the destination height, and vice versa.

SCREEN_BLIT_DESTINATION_X
The horizontal position of the rectangle in the destination buffer.

The offset is the distance, in pixels, from the left edge of the destination buffer. If this attribute isn't specified, then a default of 0 is used.

SCREEN_BLIT_DESTINATION_Y
The vertical position of the rectangle in the destination buffer.

The offset is the distance, in pixels, from the top edge of the destination buffer. If this attribute isn't specified, then a default of 0 is used.

SCREEN_BLIT_DESTINATION_WIDTH
The width, in pixels, of the rectangle in the destination buffer.

The width doesn't have to match the source width. If the destination width is larger, the source rectangle is stretched. If the destination width is smaller than the source width, the source rectangle is compressed. If this attribute isn't specified, then the destination buffer width is used.

SCREEN_BLIT_DESTINATION_HEIGHT
The height, in pixels, of the rectangle in the destination buffer.

The height doesn't have to match the source height. If the destination height is larger, the source rectangle is stretched. If the destination height is smaller than the source height, the source rectangle is compressed. If this attribute isn't specified, then the destination buffer height is used.

SCREEN_BLIT_GLOBAL_ALPHA
A global transparency value that's used to blend the source onto the destination.

If this attribute isn't specified, then a default of 255 is used; this default indicates that no global transparency is applied to the source.

SCREEN_BLIT_TRANSPARENCY
A transparency operation.

The transparency setting defines how the alpha channel, if present, is used to combine the source and destination pixels. The transparency values must be of type Screen transparency types. If this attribute isn't specified, then a default of SCREEN_TRANSPARENCY_NONE is used.

SCREEN_BLIT_SCALE_QUALITY
A scale quality value.

The scale quality setting defines the type and amount of filtering applied when scaling is required. If the source and destination rectangles are identical in size, the scale quality setting isn't used. The scale quality value must be of type Screen scale quality types. If this attribute isn't specified, then a default of SCREEN_QUALITY_NORMAL is used.

SCREEN_BLIT_COLOR
The color that's used by screen_fill().

The color format is alpha value in bits 24 to 31, red in bits 16 to 23, green in bits 8 to 15 and blue in bits 0 to 7. If this attribute isn't specified, then a default of #00000000 (transparent) is used.

SCREEN_BLIT_ROTATION
The rotation that screen_blit() supports (screen_fill() doesn't support this blit attribute).

The values must be of type Screen rotation types. If this attribute isn't specified, then a default of SCREEN_ROTATION_NONE is used.

Library:

libscreen

Description:

Note that support for each of the blit attributes is blitter-dependent. Different blitters have different capabilities and may even vary in how they each support these blit attributes.