kit_core.h as of 2023/9/13

/**
 * \file kit_core.h
 * \brief Header file for KIT SDL2's core library
 */
#ifndef _KIT_CORE_H
#define _KIT_CORE_H
#ifndef _KIT_SDL2_CORE_H
#define _KIT_SDL2_CORE_H




#include <SDL2/SDL.h>




/* ++++++++++ */
/* +kit_core+ */
/* ++++++++++ */

#if defined(_KIT_CORE_DEBUG) || defined(_KIT_ALL_DEBUG)
#define kit_coreLog(...) SDL_Log(__VA_ARGS__)
#else
#define kit_coreLog(...) ;
#endif



extern const SDL_bool kit_coreIsDebug;

extern const char kit_coreBoolStr[2][6];


extern int kit_coreMemset(void* ptr, int value, size_t size);

extern int kit_coreRealloc(void* ptr_p, size_t size_old, size_t size_new);


extern int kit_coreInit();

extern int kit_coreQuit();

/* ---------- */
/* -kit_core- */
/* ---------- */




/* ++++++++++++++++ */
/* +kit_coreThread+ */
/* ++++++++++++++++ */

typedef struct { //32B
  SDL_Thread* thread;
  void*         data;
  SDL_mutex*    lock;
  int _,returnStatus;
} kit_coreThread;

/* ---------------- */
/* -kit_coreThread- */
/* ---------------- */




/* +++++++++++++++++++++ */
/* +kit_sdl2_coreVector+ */
/* +++++++++++++++++++++ */

//assumes that _vector is a vector pointer
 //(also assumes that z_block, lensize, and datasize are < 2^32)
#define PRINT_VECTOR(_pref, _vector) {                           \
  kit_coreLog(_pref"->type.s  =\"%s\"",(_vector)->type.s);       \
  kit_coreLog(_pref"->z_block =%u",(Uint32)(_vector)->z_block);  \
  kit_coreLog(_pref"->lensize =%u",(Uint32)(_vector)->lensize);  \
  kit_coreLog(_pref"->datasize=%u",(Uint32)(_vector)->datasize); \
  kit_coreLog(_pref"->x       =%u",(_vector)->x);                \
  kit_coreLog(_pref"->y       =%u",(_vector)->y);                \
  kit_coreLog(_pref"->z       =%u",(_vector)->z);                \
  kit_coreLog(_pref"->unit    =%u",(_vector)->unit);             \
  kit_coreLog(_pref"->lens    =%p",(_vector)->lens);             \
  kit_coreLog(_pref"->data    =%p",(_vector)->data);             }


/**
 * \name Macros for accessing data elements of a kit_coreVector*
 */
/** @{ */
#define VECTOR_INDEX_A(_type, _vector, _x,_y,_z) \
  ((_type*)(_vector)->data)[ (_x) + (_y)*(_vector)->x + (_z)*(_vector)->z_block ]

#define VECTOR_INDEX_B(_type, _vector, _x_raw,_y_raw,_z_raw) \
  ((_type*)(_vector)->data)[ (_x_raw) + (_y_raw) + (_z_raw) ]

#define VECTOR_INDEX_C(_type, _vector, _index_raw) \
  ((_type*)(_vector)->data)[ (_index_raw) ]
/** @} */


/**
 * \name Macros for accessing lengths of a kit_coreVector* 's axes
 */
/** @{ */
#define VECTOR_LENS_A(_vector, _x,_y) \
  (_vector)->lens[ (_x) + (_y)*(_vector)->x ]

#define VECTOR_LENS_B(_vector, _x_raw,_y_raw) \
  (_vector)->lens[ (_x_raw) + (_y_raw) ]

#define VECTOR_LENS_C(_vector, _index_raw) \
  (_vector)->lens[ (_index_raw) ]
/** @} */



/**
 * \brief The struct for a contiguous dynamic array
 */
typedef struct { //64B (assuming that a void* is 8 bytes)
  union {
    char   s[8]; ///< \brief String portion of ID (albeit a short string)
    Uint64    n; ///< \brief Integer portion of ID
  } /*----*/ type; ///< \brief A user-defined type identifier
  Uint64  z_block; ///< \brief Is equal to x*y
  Uint64 datasize; ///< \brief Total allocated data size, in bytes (does not include the struct itself)
  Uint32        x; ///< \brief Length of the vector's (allocated) x axis
  Uint32        y; ///< \brief Length of the vector's (allocated) y axis
  Uint32        z; ///< \brief Length of the vector's (allocated) z axis
  Uint32     unit; ///< \brief Size of each data element
  Uint32  lenslen; ///< \brief Allocated size of lens, in # of (Uint32) elements
  Uint32 _padding; ///< \brief (reserved) Used for padding to a multiple of 8 bytes
  Uint32*    lens; ///< \brief lengths for individual axes (must be <= the actual allocated size)
  void*      data; ///< \brief The actual array portion of the vector
} kit_coreVector;



/**
 * Set the size of a kit_coreVector
 * \param[in,out] Vector_p A pointer to the kit_coreVector* to be altered
 * \param[in] x_new New size for the x axis (set to 0 to leave x unchanged)
 * \param[in] y_new New size for the y axis (set to 0 to leave y unchanged)
 * \param[in] z_new New size for the z axis (set to 0 to leave z unchanged)
 * \return 0 on success, or -1 on error (call SDL_GetError() for more info)
 *
 * \sa kit_coreVectorAdd
 * \sa kit_coreVectorAppend
 */
extern int kit_coreVectorSet(kit_coreVector** Vector_p, Uint32 x_new, Uint32 y_new, Uint32 z_new);

/**
 * Add to or subtract from size of a kit_coreVector
 * \param[in,out] Vector_p A pointer to the kit_coreVector* to be altered
 * \param[in] x_add How much to increase or decrease the x axis
 * \param[in] y_add How much to increase or decrease the y axis
 * \param[in] z_add How much to increase or decrease the z axis
 * \return 0 on success, or -1 on error (call SDL_GetError() for more info)
 *
 * \sa kit_coreVectorSet
 * \sa kit_coreVectorAppend
 */
extern int kit_coreVectorAdd(kit_coreVector** Vector_p, Sint32 x_add, Sint32 y_add, Sint32 z_add);

/**
 * Append an element to the end of a kit_coreVector
 * \param[in,out] Vector_p A pointer to the kit_coreVector* to be altered
 * \param[in] src A pointer to the data to be copied to the end of the vector
 * \param[in] x_pos The x index to append to
 * \param[in] y_pos The y index to append to
 * \return The newly-created index, or -1 (0xffffffff) on error (call SDL_GetError() for more info)
 *
 * \remark *src must be *Vector_p->unit bytes in size or bad things will happen
 * \sa kit_coreVectorSet
 * \sa kit_coreVectorAdd
 */
extern Uint32 kit_coreVectorAppend(kit_coreVector** Vector_p, void* src, Uint32 x_pos, Uint32 y_pos);


/**
 * Destroy a kit_coreVector
 * \param[in,out] Vector_p A pointer to the kit_coreVector* to be destroyed (before being set to NULL)
 * \return 0 on success, or -1 on error (call SDL_GetError() for more info)
 *
 * \sa kit_coreVectorCreate
 * \sa kit_coreVectorCopy
 */
extern int kit_coreVectorDestroy(kit_coreVector** Vector_p);

/**
 * Create a new kit_coreVector
 * \param[in] x Size of the vector on the x axis
 * \param[in] y Size of the vector on the y axis
 * \param[in] z Size of the vector on the z axis
 * \param[in] unit The size of each data element, in bytes
 * \param[in] type_n A user-defined number which acts as the vector's type identifier
 * \return A pointer to a newly-created Vector struct, or NULL on error (call SDL_GetError() for more info)
 *
 * \sa kit_coreVectorDestroy
 * \sa kit_coreVectorCopy
 */
extern kit_coreVector* kit_coreVectorCreate(Uint32 x, Uint32 y, Uint32 z, Uint32 unit, Uint64 type_n);

/**
 * Create a duplicate of a kit_coreVector
 * \param[in] Vector The vector to copy
 * \return A pointer to a newly-copied Vector struct, or NULL on error (call SDL_GetError() for more info)
 *
 * \sa kit_coreVectorDestroy
 * \sa kit_coreVectorCreate
 */
extern kit_coreVector* kit_coreVectorCopy(kit_coreVector* Vector);


extern void kit_coreVectorPrintInt(kit_coreVector* Vector,const char* prefix); //debug

extern void kit_coreVectorPrintLens(kit_coreVector* Vector,const char* prefix); //debug

extern int kit_coreVectorTest(); //debug

/* --------------------- */
/* -kit_sdl2_coreVector- */
/* --------------------- */




/* ++++++++++++++ */
/* +kit_coreFstr+ */
/* ++++++++++++++ */

#ifndef _WCHAR_T_DEFINED
#  include <wchar.h>
#endif
#ifndef _FSTR
# define _FSTR
#  define fstr kit_coreFstr
#endif
#ifndef _FSTRW
# define _FSTRW
#  define fstrw kit_coreFstrw
#endif



/**
 * \brief This struct contains buffer information for fstr
 */
typedef struct {
  union {
    char*     s; ///< \brief The char portion of the string union
    wchar_t*  w; ///< \brief The wchar portion of the string union
  } /* ----- */ b; ///< \brief The actual string buffer union
  Uint32 mem_size; ///< \brief The size of the string buffer, in bytes
  Uint32 _padding; ///< \brief (unused) Another Uint32 to pad to a multiple of 8 bytes
} kit_coreFstr_t;



/**
 * Format a string, before returning that string
 * \param[in,out] buffer A pointer to a kit_coreFstr_t that contains buffer information
 * \param[in] fmt The format string; used the same way as the first argument to printf
 * \param[in] ... List of variables to be formatted, if any
 * \return A pointer to the newly-formatted string, or NULL on error (call SDL_GetError() for more info)
 *
 * \sa kit_coreFstrw
 */
extern char* kit_coreFstr(kit_coreFstr_t* buffer, const char* fmt,...);

/**
 * Format a wide string, before returning that wide string
 * \param[in,out] buffer A pointer to a kit_coreFstr_t that contains buffer information
 * \param[in] fmt The format string; used the same way as the first argument to wprintf
 * \param[in] ... List of variables to be formatted, if any
 * \return A pointer to the newly-formatted wide string, or NULL on error (call SDL_GetError() for more info)
 *
 * \sa kit_coreFstr
 */
extern wchar_t* kit_coreFstrw(kit_coreFstr_t* buffer, const wchar_t* fmt,...);


/**
 * Destroy a kit_coreFstr_t buffer
 * \param[in,out] buffer_p A pointer to the kit_coreFstr_t* to be destroyed (before being set to NULL)
 * \return 0 on success, or a negative error code (call SDL_GetError() for more info)
 *
 * \sa kit_coreFstrCreate
 */
extern int kit_coreFstrDestroy(kit_coreFstr_t** buffer_p);

/**
 * Create a new kit_coreFstr_t
 * \param[in] buffer_size the size of the string's buffer, in bytes
 * \return A pointer to a newly-created Fstr_t struct, or NULL on error (call SDL_GetError() for more info)
 *
 * \sa kit_coreFstrDestroy
 */
extern kit_coreFstr_t* kit_coreFstrCreate(Uint32 buffer_size);

/* -------------- */
/* -kit_coreFstr- */
/* -------------- */




#endif /* _KIT_SDL2_CORE_H */
#endif /* _KIT_CORE_H */