MLV_image.h(3)

📦

version 3.1.0 · 2 versions

3.1.0 · ubuntu jammy (latest)
3.1.0 · debian bookworm

🌸 MLV_image.h(3) — Library Functions Manual 🌸

okay bestie, sit down, hydrate, and get your gcc ready 💖 this is MLV_image.h, part of the MLV library's section 3 manual, and it's literally the entire blueprint for "how do I make pictures show up on my screen". It's giving ✨graphics era✨. No cap.

✨ NAME ✨

MLV_image.h — this file defines all the prototypes for the functions that let you insert images. That's it, that's the whole assignment. 🎀

✨ SYNOPSIS ✨

🦋 Définitions de type

typedef struct _MLV_Image MLV_Image — defines the Image type in the MLV library. 👑

🦋 Fonctions

MLV_Image * MLV_load_image (const char *file_image) — loads an image that's living inside a file into memory.
int MLV_save_image_as_bmp (const MLV_Image *image, const char *file_image) — saves an image into a BMP file.
MLV_Image * MLV_create_image (int width, int height) — creates an image with an opaque alpha component.
void MLV_free_image (MLV_Image *image) — frees the memory the image was using.
MLV_Image * MLV_copy_image (const MLV_Image *image) — copies an image.
MLV_Image * MLV_copy_partial_image (const MLV_Image *image, int x, int y, int width, int height) — copies part of the image.
void MLV_get_image_size (const MLV_Image *image, int *width, int *height) — hands you back the size of a given image.
int MLV_get_image_width (const MLV_Image *image) — hands you back the width of a given image.
int MLV_get_image_height (const MLV_Image *image) — hands you back the height of a given image.
void MLV_resize_image (MLV_Image *image, int width, int height) — resizes the image without respecting the original proportions (chaotic, lowkey).
void MLV_vertical_image_mirror (MLV_Image *image) — changes the image by doing a vertical reflection.
void MLV_horizontal_image_mirror (MLV_Image *image) — changes the image by doing a horizontal reflection.
void MLV_resize_image_with_proportions (MLV_Image *image, int width, int height) — this one resizes the image while respecting the original proportions. the way that it actually respects them 😌
void MLV_scale_image (MLV_Image *image, double scalar) — changes the image using a homothety (aka it stretches the image).
void MLV_rotate_image (MLV_Image *image, double rotation) — performs a rotation on a given image.
void MLV_rotate_and_scale_image (MLV_Image *image, double rotation, double scalar) — performs a rotation followed by a homothety.
void MLV_scale_xy_image (MLV_Image *image, double scalar_x, double scalar_y) — stretches the image along the X axis and the Y axis with different proportionality coefficients for the two axes.
void MLV_rotate_and_scale_xy_image (MLV_Image *image, double rotation, double scalar_x, double scalar_y) — performs a rotation, then stretches the image along the X axis and the Y axis with different proportionality coefficients for the two axes.
void MLV_draw_image (const MLV_Image *image, int x, int y) — draws a given image at a given position in the window.
void MLV_draw_partial_image (const MLV_Image *image, int x_source, int y_source, int width_source, int height_source, int x, int y) — draws part of a given image at a given position on the window.
void MLV_set_alpha_on_image (MLV_Alpha alpha, MLV_Image *image) — the image's alpha component gets replaced by a homogeneous alpha component whose value is given as a parameter.
void MLV_set_pixel_on_image (int x, int y, MLV_Color color, MLV_Image *image) — overwrites the red, blue, green and alpha components of one pixel with the ones you passed into the function.
void MLV_get_pixel (int x, int y, int *red, int *green, int *blue, int *alpha) — returns the color of the screen's pixel at a given position.
void MLV_get_pixel_on_image (const MLV_Image *image, int x, int y, int *red, int *green, int *blue, int *alpha) — returns the color of the pixel sitting at a given position of a given image.
void MLV_draw_partial_image_on_image (const MLV_Image *source_image, int source_x, int source_y, int width, int height, MLV_Image *destination_image, int destination_x, int destination_y) — draws an image into a destination image.
void MLV_draw_image_on_image (const MLV_Image *source_image, MLV_Image *destination_image, int destination_x, int destination_y) — draws an image into a destination image.
SDL_Surface * MLV_get_image_data (MLV_Image *image) — returns the image's internal data.
void MLV_save_screen () — saves the screen's image into a clipboard internal to the MLV library..
MLV_Image * MLV_get_screen () — returns the image that's on the screen.
void MLV_load_screen () — loads the image present in the MLV library's internal clipboard.

✨ Description détaillée ✨

This file defines all the prototypes for the functions that let you insert images. 💅

🎀 Auteur

Adrien Boussicault
Marc Zipstein

bestie these two are the icons who wrote it, show some respect 🫶

✨ Documentation des définitions de type ✨

🌈 `typedef struct _MLV_Image MLV_Image`

Defines the Image type in the MLV library. An image in the MLV library is a two-dimensional array where every single entry holds a color (see MLV_Color). And reminder, bestie: in MLV, colors are defined using 4 integers between 0 and 256 exclusive, and those are what we call the components:

the Red component ( R );
the Green component ( G );
the Blue component ( B );
the Alpha component, which is the transparency ( A ).

✨ Documentation des fonctions ✨

💜 `MLV_Image* MLV_copy_image (const MLV_Image * image)`

Copies an image. This function creates a brand new image that is the exact, faithful copy of the image you passed as a parameter. Managing the memory of the created image is left to the user — yes bestie, that's on you. 🙈

Paramètres

image — the image to copy.

Renvoie

the copy of the image.

💜 `MLV_Image* MLV_copy_partial_image (const MLV_Image * image, int x, int y, int width, int height)`

Copies part of the image. This function creates a brand new image that is the exact, faithful copy of one part of the image you passed as a parameter. Managing the memory of the created image is left to the user — again, on you. 🫶

Paramètres

image — the image to copy.
x — X coordinate of the North-West corner of the part of the image to copy.
y — Y coordinate of the North-West corner of the part of the image to copy.
width — width of the part of the image to copy.
height — height of the part of the image to copy.

Renvoie

the copy of the image.

Exemples

advanced/09_animation.c.

💜 `MLV_Image* MLV_create_image (int width, int height)`

Creates an image with an opaque alpha component. ✨fresh canvas energy✨

Paramètres

width — width of the image.
height — height of the image.

Renvoie

the created image.

Exemples

advanced/08_zone_click.c.

💜 `void MLV_draw_image (const MLV_Image * image, int x, int y)`

Draws a given image at a given position in the window. this is THE moment, the main character moment 🔥

Paramètres

image — the image to draw.
x — X coordinate of the position in the window of the North-West corner of the image.
y — Y coordinate of the position in the window of the North-West corner of the image.

Exemples

advanced/06_image.c, advanced/07_transparency.c, et advanced/08_zone_click.c.

💜 `void MLV_draw_image_on_image (const MLV_Image * source_image, MLV_Image * destination_image, int destination_x, int destination_y)`

Draws an image into a destination image.

Paramètres

source_image — source image.
destination_image — destination image.
destination_x — X coordinate of the position where the image should be recopied. It's the future position of the North-West corner of the portion of the image to recopy.
destination_y — Y coordinate of the position where the image should be recopied. It's the future position of the North-West corner of the portion of the image to recopy.

💜 `void MLV_draw_partial_image (const MLV_Image * image, int x_source, int y_source, int width_source, int height_source, int x, int y)`

Draws part of a given image at a given position on the window. cropping era 🎀

Paramètres

image — the image to display on the window.
x_source — the X coordinate of the North-West corner of the part of the image to display.
y_source — the Y coordinate of the North-West corner of the part of the image to display.
width_source — the width of the part of the image to display.
height_source — the height of the part of the image to display.
x — X coordinate of the position in the window of the North-West corner of the part of the image to display.
y — Y coordinate of the position in the window of the North-West corner of the part of the image to display.

💜 `void MLV_draw_partial_image_on_image (const MLV_Image * source_image, int source_x, int source_y, int width, int height, MLV_Image * destination_image, int destination_x, int destination_y)`

Draws an image into a destination image. (yes, again — this is the partial one tho 💅)

Paramètres

source_image — source image.
source_x — X coordinate of the North-West corner of the position of the portion of the image to recopy.
source_y — Y coordinate of the North-West corner of the position of the portion of the image to recopy.
width — width of the position to recopy.
height — height of the position to recopy.
destination_image — destination image.
destination_x — X coordinate of the position where the image should be recopied. It's the future position of the North-West corner of the portion of the image to recopy.
destination_y — Y coordinate of the position where the image should be recopied. It's the future position of the North-West corner of the portion of the image to recopy.

💜 `void MLV_free_image (MLV_Image * image)`

Frees the memory used by the image. bestie please actually call this, your RAM is not infinite 😭

Paramètres

image — the image to delete from memory.

Exemples

advanced/06_image.c, advanced/07_transparency.c, advanced/08_zone_click.c, et advanced/09_animation.c.

💜 `SDL_Surface* MLV_get_image_data (MLV_Image * image)`

Returns the image's internal data. This function returns a pointer to the SDL library's data structure that encodes an image.

🚨 Only use this function if you want to perform an operation on an image that doesn't exist in the MLV library. Because for real, modifying the internal data of an MLV_Image-type image can corrupt how the MLV library works. You've been warned, bestie. 💀

You can then use the SDL library's routines to modify the image. (http://libsdl.org)

Here's an example of code showing how you can recover the red, green, blue and alpha components of pixel (3,4) of the image.

int x=3, y=4;

SDL_Surface* surface = MLV_get_image_data( image );
Uint32 red, blue, green, alpha;

       // Extracting color components from a 32-bit color value
       SDL_PixelFormat *fmt;
       Uint32 pixel;

       SDL_LockSurface(surface);
       fmt = surface->format;
       pixel = *(((Uint32*) surface->pixels)+ y*surface->pitch/4 + x  );

       // Get Red component
       red = pixel & fmt->Rmask;  // Isolate red component
       red = red >> fmt->Rshift; // Shift it down to 8-bit
       red = red << fmt->Rloss;  // Expand to a full 8-bit number

       // Get Green component
       green = pixel & fmt->Gmask;  // Isolate green component
       green = green >> fmt->Gshift; // Shift it down to 8-bit
       green = green << fmt->Gloss;  // Expand to a full 8-bit number

       // Get Blue component
       blue = pixel & fmt->Bmask;  // Isolate blue component
       blue = blue >> fmt->Bshift; // Shift it down to 8-bit
       blue = blue << fmt->Bloss;  // Expand to a full 8-bit number

       // Get Alpha component
       alpha = pixel & fmt->Amask;  // Isolate alpha component
       alpha = alpha >> fmt->Ashift; // Shift it down to 8-bit
       alpha = alpha << fmt->Aloss;  // Expand to a full 8-bit number

       MLV_unlock_image( image );

Paramètres

image — the image whose internal data you wanna get. 🖼️

Renvoie

A pointer to an SDL library image. 🎀

`int MLV_get_image_height (const MLV_Image * image)`

Returns the height of a given image. Like, how many pixels tall is it? 📏

Paramètres

image — the image to analyze.

Renvoie

The height of the image. 💖

`void MLV_get_image_size (const MLV_Image * image, int * width, int * height)`

Returns the size of a given image. So you get both width and height. Iconic. ✨

Paramètres

image — the image whose size you want.
width — the width of the image.
height — the height of the image.

Exemples

advanced/06_image.c, and advanced/08_zone_click.c.

`int MLV_get_image_width (const MLV_Image * image)`

Returns the width of a given image. How wide is it? 📐

Paramètres

image — the image to analyze.

Renvoie

The width of the image. 💅

`void MLV_get_pixel (int x, int y, int * red, int * green, int * blue, int * alpha)`

Returns the color of the screen pixel at a given position. The red, blue, green, and alpha parameters can be 0. In that case, they're ignored. So you can just get the ones you care about. 🎨

Paramètres

x — X coordinate of the pixel's position.
y — Y coordinate of the pixel's position.
red — red component of the pixel.
green — green component of the pixel.
blue — blue component of the pixel.
alpha — alpha (transparency) component of the pixel.

`void MLV_get_pixel_on_image (const MLV_Image * image, int x, int y, int * red, int * green, int * blue, int * alpha)`

Returns the color of the pixel at a given position in a given image. The red, blue, green, and alpha parameters can be NULL. In that case, they're ignored. So you can pass NULL for the ones you don't need. 🖼️

Paramètres

image — image to inspect.
x — X coordinate of the pixel to inspect.
y — Y coordinate of the pixel to inspect.
red — red component of the pixel.
green — green component of the pixel.
blue — blue component of the pixel.
alpha — alpha (transparency) component of the pixel.

Exemples

advanced/08_zone_click.c.

`MLV_Image* MLV_get_screen ()`

Returns the image that's on the screen. Like, the whole screen as an image. 👑

Renvoie

The image displayed on the screen.

`void MLV_horizontal_image_mirror (MLV_Image * image)`

Modifies the image by doing a horizontal reflection. So it flips it left-to-right. 🔄

Paramètres

image — the image to modify.

`MLV_Image* MLV_load_image (const char * file_image)`

Loads an image from a file into memory. This function can load images in the following formats: ICO(Icon)/CUR(Cursor)/BMP, PNM (PPM/PGM/PBM), XPM, LBM(IFF ILBM), PCX, GIF, JPEG, PNG, TGA, TIFF, and XV. So basically all the vibes. 🌈

Bogue

This function causes a segmentation fault if used before MLV_create_window(). For now, we recommend using this function after MLV_create_window(). 😭
It's possible this function might not correctly load images that aren't 32-bit (RGBA) - bug to be tested. 🧪
BUG PRESENT ON WINDOWS AND MACOS X: When the alpha component of a pixel is 0, MLV_load_image sets the Red, Green, and Blue components of the associated pixel to 0. This bug comes from the SDL_image library. 💀

Paramètres

file_image — path to the file containing the image.

Renvoie

The loaded image. 🖼️

Exemples

advanced/06_image.c, advanced/07_transparency.c, advanced/08_zone_click.c, and advanced/09_animation.c.

`void MLV_resize_image (MLV_Image * image, int width, int height)`

Resizes the image without respecting the original proportions. The height and width of the new image become the height and width passed as parameters. So it might stretch it all weird. No cap. 😅

Paramètres

image — the image to resize.
width — the width of the image.
height — the height of the image.

`void MLV_resize_image_with_proportions (MLV_Image * image, int width, int height)`

This function resizes the image while respecting the original proportions. The resulting image is the largest possible image that fits inside the rectangle of width width and height height. So it keeps it looking right. 👌

The user can enter a negative integer for the width and height fields. These fields are then not taken into account in the image resizing. In that case, if the width (resp. height) parameter is negative, then the final image will have the width (resp. height) specified in the width (resp. height) parameter. So negative means "use this exact dimension". 🤔

Paramètres

image — the image to resize.
width — the new width of the image.
height — the new height of the image.

Exemples

advanced/06_image.c.

`void MLV_rotate_and_scale_image (MLV_Image * image, double rotation, double scalar)`

Performs a rotation followed by a homothety. So it spins and scales at the same time. 🌀

Paramètres

image — the image to modify.
rotation — the angle of rotation.
scalar — the proportionality coefficient of the homothety.

`void MLV_rotate_and_scale_xy_image (MLV_Image * image, double rotation, double scalar_x, double scalar_y)`

Performs a rotation, then stretches the image along the X and Y axes with different proportionality coefficients for each axis. So it can squish and stretch independently. 🤸

Paramètres

image — the image to modify.
rotation — the angle of rotation.
scalar_x — the proportionality coefficient for the X axis.
scalar_y — the proportionality coefficient for the Y axis.

`void MLV_rotate_image (MLV_Image * image, double rotation)`

Performs a rotation on a given image. Just a lil spin. 💫

Paramètres

image — the image to modify.
rotation — the angle of rotation.

`int MLV_save_image_as_bmp (const MLV_Image * image, const char * file_image)`

Saves an image to a BMP file. Old school. 🖼️

Bogue

This function does not save the alpha component. So transparency goes bye-bye. 😭

Paramètres

image — image to save.
file_image — path to the file containing the image.

Renvoie

0 if successful, -1 if there was an error. 💯

`void MLV_scale_image (MLV_Image * image, double scalar)`

Modifies the image using a homothety (stretches the image). So it scales it uniformly. 📈

Paramètres

image — the image to modify.
scalar — proportionality coefficient of the homothety (>1 the image is enlarged, <1 the image is shrunk). So bigger than 1 makes it bigger, less than 1 makes it smaller. 🔍

`void MLV_scale_xy_image (MLV_Image * image, double scalar_x, double scalar_y)`

Stretches the image along the X and Y axes with different proportionality coefficients for each axis. So you can make it wide and short or tall and skinny. 🦋

Paramètres

image — the image to modify.
scalar_x — the proportionality coefficient for the X axis.
scalar_y — the proportionality coefficient for the Y axis.

`void MLV_set_alpha_on_image (MLV_Alpha alpha, MLV_Image * image)`

The alpha component of the image is replaced by a homogeneous alpha component whose value is given as a parameter. Transparency plays a role when an image is drawn on the screen, or when an image is copied inside another image. When copying an image, the pixels of the final result are obtained by taking a barycenter between the pixel of the source image and that of the destination image. The barycenter weights are defined by the transparent component (alpha component) of the source image. The transparency of the destination image remains unchanged. So it blends based on the source alpha. 🎨

For example,

       couleur pixel source : RGBA( 60,80,100,128 )
       couleur destination : RGBA( 0,20,40,30 )
       couleur final après recopie :
         RGBA(
           barycentre( 60,  128,  0,   256-128 ),
           barycentre( 80,  128,  20,  256-128 ),
           barycentre( 100, 128,  40,  256-128 ),
           30
        ) =
        RGBA(
            ( 60  * 128  +  0  * (256-128) ) / 256,
            ( 80  * 128  +  20 * (256-128) ) / 256,
            ( 100 * 128  +  40 * (256-128) ) / 256,
            30
        ) =
        RGBA( 30, 50, 70, 30 )

Paramètres

image — the image to modify.
alpha — the new alpha component of the image.

Exemples

advanced/07_transparency.c.

`void MLV_set_pixel_on_image (int x, int y, MLV_Color color, MLV_Image * image)`

Overwrites the red, blue, green, and alpha components of a pixel with those passed as parameters to the function. So you're setting a pixel's color. 🖌️

Paramètres

x — the x coordinate of the pixel to modify.
y — the y coordinate of the pixel to modify.
color — the new color of the pixel.
image — the image to modify.

Exemples

advanced/08_zone_click.c.

`void MLV_vertical_image_mirror (MLV_Image * image)`

Modifies the image by doing a vertical reflection. So it flips it top-to-bottom. 🙃

Paramètres

image — the image to modify.

Auteur

Auto-generated by Doxygen for MLV-3.1.0 from the source code. 🤖

This page is from MLV-3.1.0, dated Samedi 29 Janvier 2022, and it's the manpage for MLV_image.h(3). Stay slay, besties! 💖✨

📦 where this page comes from

ubuntu jammy: libmlv3-dev 3.1.0-7 · GPL-3.0-only
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms

MLV_image.h(3)

🌸 MLV_image.h(3) — Library Functions Manual 🌸

✨ NAME ✨

✨ SYNOPSIS ✨

🦋 Définitions de type

🦋 Fonctions

✨ Description détaillée ✨

🎀 Auteur

✨ Documentation des définitions de type ✨

🌈 typedef struct _MLV_Image MLV_Image

✨ Documentation des fonctions ✨

💜 MLV_Image* MLV_copy_image (const MLV_Image * image)

💜 MLV_Image* MLV_copy_partial_image (const MLV_Image * image, int x, int y, int width, int height)

💜 MLV_Image* MLV_create_image (int width, int height)

💜 void MLV_draw_image (const MLV_Image * image, int x, int y)

💜 void MLV_draw_image_on_image (const MLV_Image * source_image, MLV_Image * destination_image, int destination_x, int destination_y)

💜 void MLV_draw_partial_image (const MLV_Image * image, int x_source, int y_source, int width_source, int height_source, int x, int y)

💜 void MLV_draw_partial_image_on_image (const MLV_Image * source_image, int source_x, int source_y, int width, int height, MLV_Image * destination_image, int destination_x, int destination_y)

💜 void MLV_free_image (MLV_Image * image)

💜 SDL_Surface* MLV_get_image_data (MLV_Image * image)

int MLV_get_image_height (const MLV_Image * image)

void MLV_get_image_size (const MLV_Image * image, int * width, int * height)

int MLV_get_image_width (const MLV_Image * image)

void MLV_get_pixel (int x, int y, int * red, int * green, int * blue, int * alpha)

void MLV_get_pixel_on_image (const MLV_Image * image, int x, int y, int * red, int * green, int * blue, int * alpha)

MLV_Image* MLV_get_screen ()

void MLV_horizontal_image_mirror (MLV_Image * image)

MLV_Image* MLV_load_image (const char * file_image)

void MLV_resize_image (MLV_Image * image, int width, int height)

void MLV_resize_image_with_proportions (MLV_Image * image, int width, int height)

void MLV_rotate_and_scale_image (MLV_Image * image, double rotation, double scalar)

void MLV_rotate_and_scale_xy_image (MLV_Image * image, double rotation, double scalar_x, double scalar_y)

void MLV_rotate_image (MLV_Image * image, double rotation)

int MLV_save_image_as_bmp (const MLV_Image * image, const char * file_image)

void MLV_scale_image (MLV_Image * image, double scalar)

void MLV_scale_xy_image (MLV_Image * image, double scalar_x, double scalar_y)

void MLV_set_alpha_on_image (MLV_Alpha alpha, MLV_Image * image)

void MLV_set_pixel_on_image (int x, int y, MLV_Color color, MLV_Image * image)

void MLV_vertical_image_mirror (MLV_Image * image)

Auteur

🌈 `typedef struct _MLV_Image MLV_Image`

💜 `MLV_Image* MLV_copy_image (const MLV_Image * image)`

💜 `MLV_Image* MLV_copy_partial_image (const MLV_Image * image, int x, int y, int width, int height)`

💜 `MLV_Image* MLV_create_image (int width, int height)`

💜 `void MLV_draw_image (const MLV_Image * image, int x, int y)`

💜 `void MLV_draw_image_on_image (const MLV_Image * source_image, MLV_Image * destination_image, int destination_x, int destination_y)`

💜 `void MLV_draw_partial_image (const MLV_Image * image, int x_source, int y_source, int width_source, int height_source, int x, int y)`

💜 `void MLV_draw_partial_image_on_image (const MLV_Image * source_image, int source_x, int source_y, int width, int height, MLV_Image * destination_image, int destination_x, int destination_y)`

💜 `void MLV_free_image (MLV_Image * image)`

💜 `SDL_Surface* MLV_get_image_data (MLV_Image * image)`

`int MLV_get_image_height (const MLV_Image * image)`

`void MLV_get_image_size (const MLV_Image * image, int * width, int * height)`

`int MLV_get_image_width (const MLV_Image * image)`

`void MLV_get_pixel (int x, int y, int * red, int * green, int * blue, int * alpha)`

`void MLV_get_pixel_on_image (const MLV_Image * image, int x, int y, int * red, int * green, int * blue, int * alpha)`

`MLV_Image* MLV_get_screen ()`

`void MLV_horizontal_image_mirror (MLV_Image * image)`

`MLV_Image* MLV_load_image (const char * file_image)`

`void MLV_resize_image (MLV_Image * image, int width, int height)`

`void MLV_resize_image_with_proportions (MLV_Image * image, int width, int height)`

`void MLV_rotate_and_scale_image (MLV_Image * image, double rotation, double scalar)`

`void MLV_rotate_and_scale_xy_image (MLV_Image * image, double rotation, double scalar_x, double scalar_y)`

`void MLV_rotate_image (MLV_Image * image, double rotation)`

`int MLV_save_image_as_bmp (const MLV_Image * image, const char * file_image)`

`void MLV_scale_image (MLV_Image * image, double scalar)`

`void MLV_scale_xy_image (MLV_Image * image, double scalar_x, double scalar_y)`

`void MLV_set_alpha_on_image (MLV_Alpha alpha, MLV_Image * image)`

`void MLV_set_pixel_on_image (int x, int y, MLV_Color color, MLV_Image * image)`

`void MLV_vertical_image_mirror (MLV_Image * image)`