/** * Byakuren - A theme color extracting library implemented by C. * * Copyright (c) 2024 XadillaX * * MIT License */ #ifndef BKR_COMMON_H_ #define BKR_COMMON_H_ #include #include #include #include "third-party/xmempool/xmempool.h" #ifdef __cplusplus extern "C" { #endif /** * @brief Version string of the Byakuren library. */ #define BKR_VERSION "1.0.1" #ifndef NULL #define NULL (0) #endif /** * @brief Safely destroy a memory pool. * * This macro checks if the pool exists before destroying it and sets the * pointer to NULL afterwards. */ #define SAFE_DESTROY_POOL(pool) \ if (pool) { \ xmem_destroy_pool(pool); \ pool = NULL; \ } /** * @brief Safely free allocated memory. * * This macro checks if the pointer is not NULL before freeing it and sets * the pointer to NULL afterwards. */ #define SAFE_FREE(pointer) \ if (pointer) { \ free(pointer); \ pointer = NULL; \ } /** * @brief Maximum value for a 32-bit signed integer. */ #define MAX_INT (2147483647) /** * @brief Convert RGB values to a 32-bit integer representation. */ #define BKR_RGB_TO_INT32(r, g, b) (((r) << 16) + ((g) << 8) + (b)) /** * @brief Check if the difference between two color components is within a given * offset. */ #define DIFF_A_B_GTE_OFFSET(item, a, b, offset) \ (abs((item)->a - (item)->b) <= offset) #define BKR_IS_GRAY_INNER(item, offset) \ DIFF_A_B_GTE_OFFSET(item, red, green, offset) && \ DIFF_A_B_GTE_OFFSET(item, red, blue, offset) && \ DIFF_A_B_GTE_OFFSET(item, green, blue, offset) /** * @brief Check if a color is considered grayscale based on a given offset. * * This macro checks if the differences between red, green, and blue components * are all within the specified offset. */ #define BKR_IS_GRAY(item, offset) (BKR_IS_GRAY_INNER(item, offset)) /** * @brief RGB color structure. * * This structure represents a color in the RGB color space. * Each component (red, green, blue) is an 8-bit unsigned integer, * allowing for 256 levels of intensity for each color channel. */ typedef struct bkr_rgb { uint8_t red; /**< Red component of the color (0-255) */ uint8_t green; /**< Green component of the color (0-255) */ uint8_t blue; /**< Blue component of the color (0-255) */ } bkr_rgb; /** * @brief Color statistics structure. * * This structure holds information about a specific color, including * its RGB values, a 32-bit integer representation, and its frequency count. * It is used to store results of color analysis operations. */ typedef struct bkr_color_stats { bkr_rgb color; /**< RGB color values */ uint32_t value; /**< 32-bit integer representation of the color */ uint32_t count; /**< Frequency count of the color */ } bkr_color_stats; /** * @brief Octree node structure for color quantization. * * This structure represents a node in the octree used for color quantization. * It stores color component sums, leaf status, pixel count, and pointers to * child nodes. */ typedef struct bkr_octree_node { uint32_t red_components; /**< Sum of red components */ uint32_t green_components; /**< Sum of green components */ uint32_t blue_components; /**< Sum of blue components */ uint8_t is_leaf; /**< Flag indicating if this node is a leaf */ uint32_t pixel_count; /**< Number of pixels represented by this node */ struct bkr_octree_node* children[8]; /**< Pointers to child nodes */ } bkr_octree_node; /** * @brief Reducible list node structure for octree color quantization. * * This structure is used to maintain a list of reducible nodes in the octree. * It is part of the mechanism for merging nodes during color reduction. */ typedef struct bkr_octree_reducible_list_node { struct bkr_octree_node* node; /**< Pointer to the octree node */ struct bkr_octree_reducible_list_node* next; /**< Pointer to the next list node */ } bkr_octree_reducible_list_node; /** * @brief Color palette array structure. * * This structure represents a color palette, containing a count of colors * and a pointer to an array of RGB color structures. */ typedef struct bkr_palette_array { uint32_t count; /**< Number of colors in the palette */ bkr_rgb* colors; /**< Pointer to an array of RGB colors */ } bkr_palette_array; /** * @brief Parameters for the minimum difference color quantization method. * * This structure holds parameters used in the minimum difference method * for color quantization, including a custom palette and grayscale offset. */ typedef struct bkr_mindiff_parameter { bkr_palette_array* palette; /**< Pointer to a custom color palette */ int16_t gray_offset; /**< Offset for determining grayscale colors */ } bkr_mindiff_parameter; /** * @brief Memory pool handle for RGB color structures. * * This global variable holds the handle to a memory pool used for * allocating bkr_rgb structures. It improves memory allocation efficiency * for frequently used RGB color objects. * * @note This library does not support multi-threading, primarily due to * limitations of the memory pool implementation. */ extern xmem_pool_handle bkr_rgb_pool; /** * @brief Initialize the Byakuren library. * * @brief This function initializes the necessary resources for the Byakuren * library. * * It creates a memory pool for RGB color structures and initializes the octree * environment. This function should be called before using any other Byakuren * library functions. * * @return 1 if initialization is successful, 0 otherwise. */ extern int bkr_init(); /** * @brief Clean up and release resources used by the Byakuren library. * * @brief This function destroys the memory pools and frees any allocated * resources. * * It should be called when the Byakuren library is no longer needed to prevent * memory leaks and ensure proper cleanup of resources. */ extern void bkr_destroy(); /** * @brief Comparison function for sorting color statistics. * * @brief This function is used as a comparator for qsort to sort * bkr_color_stats structures. * * It first compares the count of colors, sorting in descending order. If the * counts are equal, it then compares the color values, also in descending * order. * * @param a Pointer to the first color statistic to compare. * @param b Pointer to the second color statistic to compare. * @return Negative if a should come before b, positive if b should come before * a, and zero if they are equivalent. */ extern int _stats_cmp(const void* a, const void* b); #ifdef __cplusplus } #endif #endif // BKR_COMMON_H_