screen_blit()

Copy pixel data from one buffer to another

Function type:

Delayed execution

Synopsis:

#include <screen/screen.h>

int screen_blit( screen_context_t ctx, 
                 screen_buffer_t dst, 
                 screen_buffer_t src, 
                 const int *attribs );

Arguments:

ctx
A connection to screen (acquired with screen_create_context()).
dst
The buffer the data will be copied to. Typically this handle is acquired by querying the render buffers of a screen pixmap or window with screen_get_pixmap_property() or screen_get_window_property().
src
The buffer where the pixels will be copied from. This handle can be a acquired using a query of a pixmap or window’s render buffers with screen_get_pixmap_property() or screen_get_window_property().
attribs
This should contain a list of attributes that defines the blit. This list must consist of a series of token-value pairs terminated with a SCREEN_BLIT_END token. The list of supported attributes is as follows:
SCREEN_BLIT_SOURCE_X
The following element contains the horizontal position of the rectangle into the source buffer that defines the area that will be copied from. The offset is the distance in pixels from the left edge of the source buffer.

If SCREEN_BLIT_SOURCE_X is not specified, 0 will be used.

SCREEN_BLIT_SOURCE_Y
The following element contains the vertical position of the rectangle into the source buffer that defines the area that will be copied from. The offset is the distance in pixels from the top edge of the source buffer.

If SCREEN_BLIT_SOURCE_Y is not specified, 0 will be used.

SCREEN_BLIT_SOURCE_WIDTH
The following element contains the width of the rectangle into the source buffer that defines the area that will be copied from. The width is in pixels.

If SCREEN_BLIT_SOURCE_WIDTH is not specified, the source buffer width will be used.

SCREEN_BLIT_SOURCE_HEIGHT
The following element contains the height of the rectangle into the source buffer that defines the area that will be copied from. The height is also in pixels.

If SCREEN_BLIT_SOURCE_HEIGHT is not specified, the source buffer height will be used.

SCREEN_BLIT_DESTINATION_X
The following element contains the horizontal position of the rectangle into the destination buffer that defines the area that will be copied into. The offset is the distance in pixels from the left edge of the destination buffer.

If SCREEN_BLIT_DESTINATION_X is not specified, 0 will be used.

SCREEN_BLIT_DESTINATION_Y
The following element contains the vertical position of the rectangle into the destination buffer that defines the area that will be copied into. The offset is the distance in pixels from the top edge of the destination buffer.

If SCREEN_BLIT_DESTINATION_Y is not specified, 0 will be used.

SCREEN_BLIT_DESTINATION_WIDTH
The following element contains the width of the rectangle into the destination buffer that defines the area that will be copied into. The width is in pixels. The width does not have to match the source width. If the destination width is larger, the source rectangle will be stretched. If the destination width is smaller than the source width, the image will be compressed.

If SCREEN_BLIT_DESTINATION_WIDTH is not specified, the destination buffer width will be used.

SCREEN_BLIT_DESTINATION_HEIGHT
The following element contains the height of the rectangle into the destination buffer that defines the area that will be copied into. The height is also in pixels. The height does not have to match the source height. If the destination height is larger, the source rectangle will be stretched. If the destination height is smaller than the source height, the image will be compressed. Note that 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.

If SCREEN_BLIT_DESTINATION_HEIGHT is not specified, the destination buffer height will be used.

SCREEN_BLIT_GLOBAL_ALPHA
The following element contains a global transparency value that should be used to blend the source onto the destination.

If SCREEN_BLIT_GLOBAL_ALPHA is not specified, 255 will be used, indicating that no global transparency will be applied to the source.

SCREEN_BLIT_TRANSPARENCY
The following element contains a transparency operation. The transparency setting defines how the alpha channel, if present, is used to combine the source and destination pixels. The accepted transparency values are:
  • SCREEN_TRANSPARENCY_NONE

    The destination pixels are replaced by fully-visible source pixels.

  • SCREEN_TRANSPARENCY_TEST

    The destination pixels are replaced by source pixels when the alpha channel is greater than 0.

  • SCREEN_TRANSPARENCY_SOURCE_OVER

    The source pixels are blended over the destination pixels (alpha blending)..

If SCREEN_BLIT_TRANSPARENCY is not specified, SCREEN_TRANSPARENCY_NONE will be used.

SCREEN_BLIT_SCALE_QUALITY
The following element contains a scale quality value. The scale quality setting loosely defines the type and amount of filtering applied when scaling is required. If the source and destination rectangles are identical in size, the underlying implementation is allowed to ignore the scale quality setting. The accepted scale quality values are:
  • SCREEN_QUALITY_NORMAL
  • SCREEN_QUALITY_FASTEST
  • SCREEN_QUALITY_NICEST

If SCREEN_BLIT_SCALE_QUALITY is not specified, SCREEN_QUALITY_NORMAL will be used.

Library:

screen

Description:

This function requests pixels from one buffer be copied to another. The blitting API is asynchronous. The operation is queued and possibly performed later.The operation is guaranteed not to be submitted until a flush is called, or until the application posts changes to one of the context’s windows. The source and destination buffers are specified with buffer handles that should normally be acquired with screen_get_pixmap_property() or screen_get_window_property().

The attribs argument is allowed to be NULL or empty, i.e. contain a single element that is set to SCREEN_BLIT_END. In that case, the source rectangle defaults to the entire source buffer, and the destination buffer defaults to the entire destination buffer. The default transparency is none. The default global alpha value is 255, or opaque. Finally the default scale quality is normal. The tokens enumerated above can be used to change this default behavior.

Returns:

If the function succeeds, it returns 0 and the blit operation is queued. Otherwise, the function returns -1 and errno is set.

Classification:

Windowing API

Safety  Value  
Interrupt handler No
Signal handler No
Thread Yes