feat: 📝 Documentate all function in ImageUtils

src/utils/Image/ImageUtils.c

@@ -5,6 +5,20 @@
 #include "ImageUtils.h"
 
 void render_image_file(const char* file, SDL_Renderer* renderer, const SDL_Rect* srcrect, const SDL_Rect* dstrect)
+/**
+ * @brief Renders an image file onto a given SDL renderer.
+ *
+ * This function loads an image from the specified file, creates a texture from the loaded surface,
+ * and renders it onto the provided SDL renderer within the specified source and destination rectangles.
+ *
+ * @param file The path to the image file to be rendered.
+ * @param renderer The SDL_Renderer to render the image onto.
+ * @param srcrect The source rectangle to be used from the image. If NULL, the entire image is used.
+ * @param dstrect The destination rectangle on the renderer where the image will be rendered.
+ *
+ * @note The function will terminate the program with an error message if the image file cannot be loaded,
+ *       if the texture cannot be created from the surface, or if the rendering fails.
+ */
 {
 	SDL_Surface* surface = IMG_Load(file);
 	if (surface == NULL)
@@ -17,6 +31,19 @@ void render_image_file(const char* file, SDL_Renderer* renderer, const SDL_Rect*
 }
 
 void render_full_image_file(const char* file, SDL_Renderer* renderer, const SDL_Rect* dstrect)
+/**
+ * @brief Renders an entire image file onto a given SDL renderer.
+ *
+ * This function loads an image from the specified file, creates a texture from the loaded surface,
+ * and renders it onto the provided SDL renderer within the specified destination rectangle.
+ *
+ * @param file The path to the image file to be rendered.
+ * @param renderer The SDL_Renderer to render the image onto.
+ * @param dstrect The destination rectangle on the renderer where the image will be rendered.
+ *
+ * @note The function will terminate the program with an error message if the image file cannot be loaded,
+ *       if the texture cannot be created from the surface, or if the rendering fails.
+ */
 {
 	SDL_Surface* surface = IMG_Load(file);
 	if (surface == NULL)
@@ -30,6 +57,20 @@ void render_full_image_file(const char* file, SDL_Renderer* renderer, const SDL_
 }
 
 void render_surface(SDL_Surface* surface, SDL_Renderer* renderer, const SDL_Rect* srcrect, const SDL_Rect* dstrect)
+/**
+ * @brief Renders a given SDL surface onto a given SDL renderer.
+ *
+ * This function creates a texture from the provided SDL surface and renders it onto the provided SDL renderer
+ * within the specified source and destination rectangles.
+ *
+ * @param surface The SDL_Surface to be rendered.
+ * @param renderer The SDL_Renderer to render the surface onto.
+ * @param srcrect The source rectangle to be used from the surface. If NULL, the entire surface is used.
+ * @param dstrect The destination rectangle on the renderer where the surface will be rendered.
+ *
+ * @note The function will terminate the program with an error message if the texture cannot be created from the surface,
+ *       or if the rendering fails.
+ */
 {
 	SDL_Texture* text = SDL_CreateTextureFromSurface(renderer, surface);
 	if (text == NULL)
@@ -39,12 +80,38 @@ void render_surface(SDL_Surface* surface, SDL_Renderer* renderer, const SDL_Rect
 }
 
 void* get_pixel_pt(SDL_Surface* surface, size_t x, size_t y)
+/**
+ * @brief Retrieves a pointer to the pixel at the specified coordinates in an SDL surface.
+ *
+ * This function calculates the memory address of the pixel located at the given (x, y) coordinates
+ * within the provided SDL surface and returns a pointer to that pixel.
+ *
+ * @param surface The SDL_Surface from which to retrieve the pixel.
+ * @param x The x-coordinate of the pixel.
+ * @param y The y-coordinate of the pixel.
+ * @return A pointer to the pixel at the specified coordinates.
+ *
+ * @note The function assumes that the coordinates are within the bounds of the surface.
+ */
 {
 	size_t bpp = (size_t)surface->format->BytesPerPixel;
 	return (void*)((size_t)surface->pixels + (y * (size_t)surface->pitch + x * bpp));
 }
 
 Uint32 get_pixel_val(void* pixel, SDL_PixelFormat* format)
+/**
+ * @brief Retrieves the pixel value from a given pixel pointer and SDL pixel format.
+ *
+ * This function extracts the pixel value from the provided pixel pointer based on the
+ * specified SDL pixel format. It handles different bytes per pixel (bpp) cases and
+ * returns the pixel value as a Uint32.
+ *
+ * @param pixel A pointer to the pixel data.
+ * @param format The SDL_PixelFormat structure that describes the format of the pixel.
+ * @return The pixel value as a Uint32.
+ *
+ * @note The function assumes that the pixel pointer and format are valid and properly initialized.
+ */
 {
 	Uint32 pixel32;
 
@@ -76,6 +143,19 @@ Uint32 get_pixel_val(void* pixel, SDL_PixelFormat* format)
 }
 
 void set_pixel_val(void* pixel, SDL_PixelFormat* format, Uint32 val)
+/**
+ * @brief Sets the pixel value at a given memory location based on the SDL pixel format.
+ *
+ * This function assigns a new pixel value to the specified memory location, interpreting
+ * the memory layout according to the provided SDL pixel format. It handles different
+ * bytes per pixel (bpp) cases and sets the pixel value accordingly.
+ *
+ * @param pixel A pointer to the memory location where the pixel value should be set.
+ * @param format The SDL_PixelFormat structure that describes the format of the pixel.
+ * @param val The new pixel value to be set.
+ *
+ * @note The function assumes that the pixel pointer and format are valid and properly initialized.
+ */
 {
 	int bpp = format->BytesPerPixel;
 
@@ -110,6 +190,18 @@ void set_pixel_val(void* pixel, SDL_PixelFormat* format, Uint32 val)
 }
 
 void pixel_to_grayscale(void* pixel, SDL_PixelFormat* format)
+/**
+ * @brief Converts a pixel to grayscale.
+ *
+ * This function takes a pointer to a pixel and its format, converts the pixel's color
+ * to grayscale by averaging its red, green, and blue components, and then sets the pixel
+ * to the resulting grayscale value.
+ *
+ * @param pixel A pointer to the pixel data.
+ * @param format The SDL_PixelFormat structure that describes the format of the pixel.
+ *
+ * @note The function assumes that the pixel pointer and format are valid and properly initialized.
+ */
 {
 	Uint32* pixel32 = (Uint32*)pixel;
 
@@ -125,6 +217,19 @@ void pixel_to_grayscale(void* pixel, SDL_PixelFormat* format)
 }
 
 void pixel_to_black_white(void* pixel, SDL_PixelFormat* format, Uint8 threshold)
+/**
+ * @brief Converts a pixel to black or white based on a threshold.
+ *
+ * This function takes a pointer to a pixel and its format, converts the pixel's color
+ * to grayscale by averaging its red, green, and blue components, and then sets the pixel
+ * to either black or white based on the provided threshold.
+ *
+ * @param pixel A pointer to the pixel data.
+ * @param format The SDL_PixelFormat structure that describes the format of the pixel.
+ * @param threshold The threshold value used to determine whether the pixel should be black or white.
+ *
+ * @note The function assumes that the pixel pointer and format are valid and properly initialized.
+ */
 {
 	Uint8 r;
 	Uint8 g;
@@ -151,6 +256,17 @@ void pixel_to_black_white(void* pixel, SDL_PixelFormat* format, Uint8 threshold)
 }
 
 void image_to_black_white(SDL_Surface* surface)
+/**
+ * @brief Converts an entire SDL surface to black and white.
+ *
+ * This function iterates over each pixel in the provided SDL surface,
+ * converts each pixel to black or white based on a fixed threshold,
+ * and updates the surface with the new pixel values.
+ *
+ * @param surface The SDL_Surface to be converted to black and white.
+ *
+ * @note The function will terminate the program with an error message if the surface cannot be locked.
+ */
 {
     if (SDL_LockSurface(surface) < 0)
         errx(1, "image_to_black_white: fail to lock surface!");
@@ -169,6 +285,20 @@ void image_to_black_white(SDL_Surface* surface)
 }
 
 SDL_Surface* create_sub_surface(SDL_Surface* surface, SDL_Rect rect)
+/**
+ * @brief Creates a sub-surface from a given SDL surface and rectangle.
+ *
+ * This function creates a new SDL surface that represents a sub-region of the
+ * provided surface, defined by the specified rectangle. The pixel data from
+ * the original surface within the rectangle is copied to the new sub-surface.
+ *
+ * @param surface The original SDL_Surface from which to create the sub-surface.
+ * @param rect The SDL_Rect that defines the region of the original surface to be copied.
+ * @return A new SDL_Surface representing the sub-region of the original surface.
+ *
+ * @note The function will terminate the program with an error message if the sub-surface
+ *       cannot be created.
+ */
 {
 	SDL_Surface* sub = SDL_CreateRGBSurface(0,rect.w,rect.h,32,0,0,0,0);
 
@@ -199,6 +329,20 @@ SDL_Surface* create_sub_surface(SDL_Surface* surface, SDL_Rect rect)
 
 
 SDL_Surface* rotate_pixels(SDL_Surface* surface, double angle) {
+    /**
+     * @brief Rotates the pixels of an SDL surface by a given angle.
+     *
+     * This function creates a new SDL surface with the dimensions adjusted to fit the rotated image.
+     * It then rotates the pixels of the original surface by the specified angle and copies them to the new surface.
+     * The background color of the new surface is set to white.
+     *
+     * @param surface The original SDL_Surface to be rotated.
+     * @param angle The angle in degrees by which to rotate the surface.
+     * @return A new SDL_Surface containing the rotated image.
+     *
+     * @note The function will terminate the program with an error message if the rotated surface cannot be created,
+     *       or if the surfaces cannot be locked.
+     */
     int original_w = surface->w;
     int original_h = surface->h;