image¶

struct image¶

struct image¶

Images are the visual building blocks of your game. Use images to draw on screen, or as sources for sprites and fonts. Images can be read from a file or created empty and can be used directly or provide frames for sprites or characters for fonts.

The simplest form of creating an image is by using create_image():

struct image* image;
image = create_image("path/to/image.png");

Images can also be used as a drawing target instead of the screen:

draw_on_image(image);
// draw images, sprites or text
draw_on_screen();

You will have to explicitly get rid of any image you create using destroy_image():

destroy_image(image);

Not doing so will result a memory leak.

create_image¶

struct image *create_image(const char *filepath)¶

Create and load an image using a PNG file

Return

image pointer or NULL on failure

Parameters

• filepath -

  File path to the image file

create_blank_image¶

struct image *create_blank_image(int width, int height)¶

Create a blank image for direct pixel manipulation

Return

image pointer or NULL on failure

Parameters

• width -

  The width of the blank image

• height -

  The height of the blank image

create_target_image¶

struct image *create_target_image(int width, int height, struct color color)¶

Create an image that can be used to draw other images or sprites on.

Return

image pointer or NULL on failure

Parameters

• width -

  The width of the blank image

• height -

  The height of the blank image

• color -

  The default color of the target image

destroy_image¶

void destroy_image(struct image *image)¶

Destroy an image created using create_image() or create_blank_image()

Parameters

• image -

  A valid image pointer created using create_image()

draw_image¶

void draw_image(struct image *image, int x, int y, struct rectangle *clip, double angle)¶

Draw an image on the screen

Parameters

• image -

  Image to draw

• x -

  X position

• y -

  Y position

• clip -

  Rectangle to draw

• angle -

  Rotate image in degrees

get_image_alpha¶

uint8_t get_image_alpha(struct image *image)¶

Get the current image alpha value (opacity).

Return

0-255 alpha value

Parameters

• image -

  Image to query

set_image_alpha¶

void set_image_alpha(struct image *image, uint8_t alpha)¶

Set the image alpha value (opacity).

Parameters

• image -

  Image to query

• alpha -

  A new 0-255 alpha value

set_blend_mode¶

void set_blend_mode(struct image * image, enum blend_mode blend_mode)

Set the method to use when drawing an image

Parameters

• image -

  image The blend method will work for

• blend_mode -

  The blend method to apply

load_image¶

cleanup_image¶

int cleanup_image(struct image *image)¶

Cleanup any initialized image resources Cleanup will free all internally allocated resources for this image, making it ready for deallocation.

Parameters

• image -

  Existing image to cleanup

Note

You don’t need to use cleanup_image() if you use destroy_image()

Return

-1 on error

lock_image¶

int lock_image(struct image *image, void **pixels, int *pitch)¶

Lock a image to get pixel level access

Return

0 on success or -1 on error

Parameters

• image -

  Image to lock

• pixels -

  pointer reference to the image pixels lock_image() will provide you with

• pitch -

  pointer to update with the pixel pitch

unlock_image¶

int unlock_image(struct image *image)¶

Unlock a locked image once you are done with it

Return

0 on success or -1 on error

Parameters

• image -

  Locked image to unlock

draw_on_image¶

void draw_on_image(struct image *image)¶

Switch to draw on an image instead of the actual screen

Parameters

• image -

  Image to draw on to

pixels_collide¶

int pixels_collide(struct image *img1, struct rectangle *rect1, struct image *img2, struct rectangle *rect2)¶

Test if two images have colliding pixels

Return

1 if collision was found 0 if no collisions were found -1 when error occured

Parameters

• img1 -

  First image to test

• rect1 -

  Area in first image to test

• img2 -

  Second image to test

• rect2 -

  Area in second image to test