kit_core.h as of 8-18-23

/**
 * \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+ */
extern int kit_coreInit();
extern int kit_coreQuit();
/* -kit_core- */



/* +kit_coreThread+ */
typedef struct {
  SDL_Thread* thread;
  void*         data;
  SDL_mutex*    lock;
  int   returnStatus;
  int          state;
} kit_coreThread;
/* -kit_coreThread- */



/* +kit_sdl2_coreVector+ */
//extern void _kit_coreVectorPrintInt(kit_coreVector* Vector,const char* prefix);

/**
 * \brief The struct for a contiguous dynamic array.
 */
typedef struct {
  union {
    char    s[4]; ///< \brief String portion of ID (albeit a short string).
    Uint32     n; ///< \brief Integer portion of ID.
  } /* --- */ type; ///< \brief A user-defined type identifier.
  Uint32         x; ///< \brief Length of the vector's x axis.
  Uint32         y; ///< \brief Length of the vector's y axis (0 means the axis is nonexistent).
  Uint32         z; ///< \brief Length of the vector's z axis (0 means the axis is nonexistent).
  Uint32      unit; ///< \brief size of each data element.
  Sint32     _dims; ///< \brief (read only) 1=1D, 2=2D, 3=3D.
  union {
    void *p1d, **p2d, ***p3d, *ptr; ///< \brief The actual array portion of the vector.
  };
} kit_coreVector;


/**
 * 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 a negative error code (call SDL_GetError() for more info).
 *
 * \remark As stated in kit_coreVectorSet, vectors cannot change from 1D -> 2D, 2D -> 3D, etc.
 * \sa kit_coreVectorSet
 */
extern int kit_coreVectorAdd(kit_coreVector** Vector_p, Sint32 x_add, Sint32 y_add, Sint32 z_add);

/**
 * 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 a negative error code (call SDL_GetError() for more info).
 *
 * \remark The result of a size change cannot turn a 1D vector to a 2D one, vice versa, and so on.
 * \sa kit_coreVectorAdd
 */
extern int kit_coreVectorSet(kit_coreVector** Vector_p, Uint32 x_new, Uint32 y_new, Uint32 z_new);


/**
 * 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 a negative error code (call SDL_GetError() for more info).
 * \sa kit_coreVectorCreate
 */
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 (set to 0 to disable the axis entirely).
 * \param[in] z Size of the vector on the z axis (set to 0 to disable the axis entirely).
 * \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.
 * \param[out] returnStatus_p A pointer to an int to be filled with the error code (can be NULL).
 * \return A pointer to a newly-created Vector struct, or NULL on error (call SDL_GetError() for more info).
 *
 * \remark "unit" determines of each DATA element, which is to say, while a 1D vector's element size is
           equal to unit on the x axis, a 2D vector's element size on the x axis will be that of a void*.
 * \remark Whether or not returnStatus_p is NULL, SDL_GetError() will be set in the event of an error.
 * \sa kit_coreVectorDestroy
 */
extern kit_coreVector* kit_coreVectorCreate(Uint32 x, Uint32 y, Uint32 z,
                                            Uint32 unit, Uint32 type_n,
                                            int* returnStatus_p);
/* -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 */