Copying Pixels

FUNCTIONS

  int     copy_rect(Graphics *g, Point dp, Graphics *src, Rect sr);
  void    texture_rect(Graphics *g, Rect dr, Graphics *src, Rect sr);
  void    draw_image(Graphics *g, Rect dr, Image *img, Rect sr);
  Bitmap *image_to_bitmap(Window *win, Image *img);

NOTES

The copy_rect operation copies pixels from the source rectangle sr in the source graphics object src, to the destination point dp in the destination graphics object g. There are some restrictions on this function:

• Copying pixels from bitmaps into images will not work. Bitmaps are output devices.
• Copying pixels from windows into images will not work. Windows are output devices.
• Copying from bitmaps to windows is only guaranteed to work if the bitmap has the same arrangement of colour data as the window (i.e. that window was passed as a parameter to new_bitmap when creating the bitmap).
• Copying bitmaps to other bitmaps is only guaranteed to work if the two bitmaps share the same colour data arrangement.
• Copying from a window to a bitmap shares the same restriction, but additionally might produce incorrect pixels if portions of the source window are obscured by another window.
• Copying from a window to another window shares the same restrictions, for the same reasons.
• Copying from a window to itself is an exception; this is guaranteed to work because any portions which are obscured while copying will be refreshed automatically by calling the window's redraw call-back during the next event-handling cycle. Hence, this function can be used to perform window scrolling.

For these reasons, it is best to think of bitmaps and windows as output devices only, with copying going from images to bitmaps to windows, but never in the other direction:

Valid drawing destinations.

The texture_rect function overlays the entire destination rectangle dr with copies of the source rectangle sr from the pixel source src, starting in the top-left point of dr and proceeding to the left and down. This produces a wall-paper effect.

The draw_image function specialises in drawing a scaled version of an image. It copies pixels from the source rectangle sr of the image img into the destination rectangle dr, scaling between the two rectangles as required. When drawing an image many times, it is sometimes more efficient to scale the image first then use copy_rect instead of draw_image, since the scaling is only performed once.

Drawing an image to a bitmap or window is implemented by creating a temporary bitmap, copying the image data into the bitmap, copying the bitmap to the window, then destroying the temporary bitmap. For this reason, when drawing an image many times, it is sometimes more efficient to create a bitmap from the image using image_to_bitmap, and then draw from that bitmap instead.

EXAMPLES

• imgtest.c