work for 2024-11-21 (10/10)

/******************************************************************************/
/******************************************************************************/
//"2024-11-21\include\kit\_video_PixelFmt.hpp":
#ifndef _INC__VIDEO_PIXELFMT_HPP
#define _INC__VIDEO_PIXELFMT_HPP

#include "commondef.hpp"


namespace kit {





enum BlendModesEnum {
  BLENDMODE_NONE  = 0x00000000, //no blending
                                  //dstRGBA = srcRGBA
  BLENDMODE_BLEND = 0x00000001, //alpha blending
                                  //dstRGB = (srcRGB * srcA) + (dstRGB * (1-srcA))
                                  //dstA = srcA + (dstA * (1-srcA))
  BLENDMODE_ADD   = 0x00000002, //additive blending
                                  //dstRGB = (srcRGB * srcA) + dstRGB
                                  //dstA = dstA
  BLENDMODE_MOD   = 0x00000004, //color modulate
                                  //dstRGB = srcRGB * dstRGB
                                  //dstA = dstA
  BLENDMODE_MUL   = 0x00000008, //color multiply
                                  //dstRGB = (srcRGB * dstRGB) + (dstRGB * (1-srcA))
                                  //dstA = dstA

  BLENDMODE_INVALID = 0x7FFFFFFF,

};





enum PixelTypeEnum {
  PIXELTYPE_UNKNOWN,
  PIXELTYPE_INDEX1,
  PIXELTYPE_INDEX4,
  PIXELTYPE_INDEX8,
  PIXELTYPE_PACKED8,
  PIXELTYPE_PACKED16,
  PIXELTYPE_PACKED32,
  PIXELTYPE_ARRAYU8,
  PIXELTYPE_ARRAYU16,
  PIXELTYPE_ARRAYU32,
  PIXELTYPE_ARRAYF16,
  PIXELTYPE_ARRAYF32,
};

enum PixelOrderEnum { //bitmap pixel order, high bit -> low bit
  PIXELORDER_NONE,
  PIXELORDER_4321,
  PIXELORDER_1234,
};

enum PackedOrderEnum { //packed component order, high bit -> low bit
  PACKEDORDER_NONE,
  PACKEDORDER_XRGB,
  PACKEDORDER_RGBX,
  PACKEDORDER_ARGB,
  PACKEDORDER_RGBA,
  PACKEDORDER_XBGR,
  PACKEDORDER_BGRX,
  PACKEDORDER_ABGR,
  PACKEDORDER_BGRA,
};

enum ArrayOrderEnum { //array component order, low byte -> high byte
  ARRAYORDER_NONE,
  ARRAYORDER_RGB,
  ARRAYORDER_RGBA,
  ARRAYORDER_ARGB,
  ARRAYORDER_BGR,
  ARRAYORDER_BGRA,
  ARRAYORDER_ABGR,
};

enum PackedLayoutEnum { //packed component layout
  PACKEDLAYOUT_NONE,
  PACKEDLAYOUT_332,
  PACKEDLAYOUT_4444,
  PACKEDLAYOUT_1555,
  PACKEDLAYOUT_5551,
  PACKEDLAYOUT_565,
  PACKEDLAYOUT_8888,
  PACKEDLAYOUT_2101010,
  PACKEDLAYOUT_1010102,
};

#define KIT_DEFINE_PIXELFOURCC(A, B, C, D) ( \
  (  ((u32)((u8)(A)))<< 0  )  | \
  (  ((u32)((u8)(B)))<< 8  )  | \
  (  ((u32)((u8)(C)))<<16  )  | \
  (  ((u32)((u8)(D)))<<24  )    )

#define KIT_DEF_PIXELFMT(type, order, layout, bits, bytes) \
    ((1 << 28) | ((type) << 24) | ((order) << 20) | ((layout) << 16) | \
     ((bits) << 8) | ((bytes) << 0))

#define KIT_PIXELFLAG(X)    (((X) >> 28) & 0x0F)
#define KIT_PIXELTYPE(X)    (((X) >> 24) & 0x0F)
#define KIT_PIXELORDER(X)   (((X) >> 20) & 0x0F)
#define KIT_PIXELLAYOUT(X)  (((X) >> 16) & 0x0F)
#define KIT_BITSPERPIXEL(X) (((X) >> 8) & 0xFF)
#define KIT_BYTESPERPIXEL(X) \
    (KIT_ISPIXELFORMAT_FOURCC(X) ? \
        ((((X) == PIXELFMT_YUY2) || \
          ((X) == PIXELFMT_UYVY) || \
          ((X) == PIXELFMT_YVYU)) ? 2 : 1) : (((X) >> 0) & 0xFF))

#define KIT_ISPIXELFORMAT_INDEXED(format)   \
    (!KIT_ISPIXELFORMAT_FOURCC(format) && \
     ((KIT_PIXELTYPE(format) == PIXELTYPE_INDEX1) || \
      (KIT_PIXELTYPE(format) == PIXELTYPE_INDEX4) || \
      (KIT_PIXELTYPE(format) == PIXELTYPE_INDEX8)))

#define KIT_ISPIXELFORMAT_PACKED(format) \
    (!KIT_ISPIXELFORMAT_FOURCC(format) && \
     ((KIT_PIXELTYPE(format) == PIXELTYPE_PACKED8) || \
      (KIT_PIXELTYPE(format) == PIXELTYPE_PACKED16) || \
      (KIT_PIXELTYPE(format) == PIXELTYPE_PACKED32)))

#define KIT_ISPIXELFORMAT_ARRAY(format) \
    (!KIT_ISPIXELFORMAT_FOURCC(format) && \
     ((KIT_PIXELTYPE(format) == PIXELTYPE_ARRAYU8) || \
      (KIT_PIXELTYPE(format) == PIXELTYPE_ARRAYU16) || \
      (KIT_PIXELTYPE(format) == PIXELTYPE_ARRAYU32) || \
      (KIT_PIXELTYPE(format) == PIXELTYPE_ARRAYF16) || \
      (KIT_PIXELTYPE(format) == PIXELTYPE_ARRAYF32)))

#define KIT_ISPIXELFORMAT_ALPHA(format)   \
    ((KIT_ISPIXELFORMAT_PACKED(format) && \
     ((KIT_PIXELORDER(format) == PACKEDORDER_ARGB) || \
      (KIT_PIXELORDER(format) == PACKEDORDER_RGBA) || \
      (KIT_PIXELORDER(format) == PACKEDORDER_ABGR) || \
      (KIT_PIXELORDER(format) == PACKEDORDER_BGRA))) || \
    (KIT_ISPIXELFORMAT_ARRAY(format) && \
     ((KIT_PIXELORDER(format) == ARRAYORDER_ARGB) || \
      (KIT_PIXELORDER(format) == ARRAYORDER_RGBA) || \
      (KIT_PIXELORDER(format) == ARRAYORDER_ABGR) || \
      (KIT_PIXELORDER(format) == ARRAYORDER_BGRA))))

//The flag is set to 1 because 0x1? is not in the printable ASCII range
#define KIT_ISPIXELFORMAT_FOURCC(format)    \
    ((format) && (KIT_PIXELFLAG(format) != 1))

enum PixelFormatEnum {
    PIXELFMT_UNKNOWN,
    PIXELFMT_INDEX1LSB   = KIT_DEF_PIXELFMT(PIXELTYPE_INDEX1, PIXELORDER_4321, 0, 1, 0),
    PIXELFMT_INDEX1MSB   = KIT_DEF_PIXELFMT(PIXELTYPE_INDEX1, PIXELORDER_1234, 0, 1, 0),
    PIXELFMT_INDEX4LSB   = KIT_DEF_PIXELFMT(PIXELTYPE_INDEX4, PIXELORDER_4321, 0, 4, 0),
    PIXELFMT_INDEX4MSB   = KIT_DEF_PIXELFMT(PIXELTYPE_INDEX4, PIXELORDER_1234, 0, 4, 0),
    PIXELFMT_INDEX8      = KIT_DEF_PIXELFMT(PIXELTYPE_INDEX8,               0, 0, 8, 1),

    PIXELFMT_RGB332      = KIT_DEF_PIXELFMT(PIXELTYPE_PACKED8 , PACKEDORDER_XRGB, PACKEDLAYOUT_332 ,  8, 1),
    PIXELFMT_XRGB4444    = KIT_DEF_PIXELFMT(PIXELTYPE_PACKED16, PACKEDORDER_XRGB, PACKEDLAYOUT_4444, 12, 2),
    PIXELFMT_XBGR4444    = KIT_DEF_PIXELFMT(PIXELTYPE_PACKED16, PACKEDORDER_XBGR, PACKEDLAYOUT_4444, 12, 2),
    PIXELFMT_XRGB1555    = KIT_DEF_PIXELFMT(PIXELTYPE_PACKED16, PACKEDORDER_XRGB, PACKEDLAYOUT_1555, 15, 2),
    PIXELFMT_XBGR1555    = KIT_DEF_PIXELFMT(PIXELTYPE_PACKED16, PACKEDORDER_XBGR, PACKEDLAYOUT_1555, 15, 2),
    PIXELFMT_ARGB4444    = KIT_DEF_PIXELFMT(PIXELTYPE_PACKED16, PACKEDORDER_ARGB, PACKEDLAYOUT_4444, 16, 2),
    PIXELFMT_RGBA4444    = KIT_DEF_PIXELFMT(PIXELTYPE_PACKED16, PACKEDORDER_RGBA, PACKEDLAYOUT_4444, 16, 2),
    PIXELFMT_ABGR4444    = KIT_DEF_PIXELFMT(PIXELTYPE_PACKED16, PACKEDORDER_ABGR, PACKEDLAYOUT_4444, 16, 2),
    PIXELFMT_BGRA4444    = KIT_DEF_PIXELFMT(PIXELTYPE_PACKED16, PACKEDORDER_BGRA, PACKEDLAYOUT_4444, 16, 2),
    PIXELFMT_ARGB1555    = KIT_DEF_PIXELFMT(PIXELTYPE_PACKED16, PACKEDORDER_ARGB, PACKEDLAYOUT_1555, 16, 2),
    PIXELFMT_RGBA5551    = KIT_DEF_PIXELFMT(PIXELTYPE_PACKED16, PACKEDORDER_RGBA, PACKEDLAYOUT_5551, 16, 2),
    PIXELFMT_ABGR1555    = KIT_DEF_PIXELFMT(PIXELTYPE_PACKED16, PACKEDORDER_ABGR, PACKEDLAYOUT_1555, 16, 2),
    PIXELFMT_BGRA5551    = KIT_DEF_PIXELFMT(PIXELTYPE_PACKED16, PACKEDORDER_BGRA, PACKEDLAYOUT_5551, 16, 2),
    PIXELFMT_RGB565      = KIT_DEF_PIXELFMT(PIXELTYPE_PACKED16, PACKEDORDER_XRGB, PACKEDLAYOUT_565 , 16, 2),
    PIXELFMT_BGR565      = KIT_DEF_PIXELFMT(PIXELTYPE_PACKED16, PACKEDORDER_XBGR, PACKEDLAYOUT_565 , 16, 2),

    PIXELFMT_RGB24       = KIT_DEF_PIXELFMT(PIXELTYPE_ARRAYU8, ARRAYORDER_RGB, 0, 24, 3),
    PIXELFMT_BGR24       = KIT_DEF_PIXELFMT(PIXELTYPE_ARRAYU8, ARRAYORDER_BGR, 0, 24, 3),

    PIXELFMT_XRGB8888    = KIT_DEF_PIXELFMT(PIXELTYPE_PACKED32, PACKEDORDER_XRGB, PACKEDLAYOUT_8888, 24, 4),
    PIXELFMT_RGBX8888    = KIT_DEF_PIXELFMT(PIXELTYPE_PACKED32, PACKEDORDER_RGBX, PACKEDLAYOUT_8888, 24, 4),
    PIXELFMT_XBGR8888    = KIT_DEF_PIXELFMT(PIXELTYPE_PACKED32, PACKEDORDER_XBGR, PACKEDLAYOUT_8888, 24, 4),
    PIXELFMT_BGRX8888    = KIT_DEF_PIXELFMT(PIXELTYPE_PACKED32, PACKEDORDER_BGRX, PACKEDLAYOUT_8888, 24, 4),
    PIXELFMT_ARGB8888    = KIT_DEF_PIXELFMT(PIXELTYPE_PACKED32, PACKEDORDER_ARGB, PACKEDLAYOUT_8888, 32, 4),
    PIXELFMT_RGBA8888    = KIT_DEF_PIXELFMT(PIXELTYPE_PACKED32, PACKEDORDER_RGBA, PACKEDLAYOUT_8888, 32, 4),
    PIXELFMT_ABGR8888    = KIT_DEF_PIXELFMT(PIXELTYPE_PACKED32, PACKEDORDER_ABGR, PACKEDLAYOUT_8888, 32, 4),
    PIXELFMT_BGRA8888    = KIT_DEF_PIXELFMT(PIXELTYPE_PACKED32, PACKEDORDER_BGRA, PACKEDLAYOUT_8888, 32, 4),
    PIXELFMT_ARGB2101010 = KIT_DEF_PIXELFMT(PIXELTYPE_PACKED32, PACKEDORDER_ARGB, PACKEDLAYOUT_2101010, 32, 4),


    //these are actually what is returned by getPixelFmtName(),
     //so instead of "PIXELFMT_XRGB4444", it would return "PIXELFMT_RGB444"
    PIXELFMT_RGB444 = PIXELFMT_XRGB4444,
    PIXELFMT_BGR444 = PIXELFMT_XBGR4444,
    PIXELFMT_RGB555 = PIXELFMT_XRGB1555,
    PIXELFMT_BGR555 = PIXELFMT_XBGR1555,
    PIXELFMT_RGB888 = PIXELFMT_XRGB8888,
    PIXELFMT_BGR888 = PIXELFMT_XBGR8888,

    //aliases for convenenience
    PIXELFMT_RGBA32 = PIXELFMT_ABGR8888,
    PIXELFMT_ARGB32 = PIXELFMT_BGRA8888,
    PIXELFMT_BGRA32 = PIXELFMT_ARGB8888,
    PIXELFMT_ABGR32 = PIXELFMT_RGBA8888,


    PIXELFMT_YV12 = KIT_DEFINE_PIXELFOURCC('Y', 'V', '1', '2'), //Planar mode: Y + V + U            (3 planes)
    PIXELFMT_IYUV = KIT_DEFINE_PIXELFOURCC('I', 'Y', 'U', 'V'), //Planar mode: Y + U + V            (3 planes)
    PIXELFMT_YUY2 = KIT_DEFINE_PIXELFOURCC('Y', 'U', 'Y', '2'), //Packed mode: Y0 + U0 + Y1 + V0    (1 plane )
    PIXELFMT_UYVY = KIT_DEFINE_PIXELFOURCC('U', 'Y', 'V', 'Y'), //Packed mode: U0 + Y0 + V0 + Y1    (1 plane )
    PIXELFMT_YVYU = KIT_DEFINE_PIXELFOURCC('Y', 'V', 'Y', 'U'), //Packed mode: Y0 + V0 + Y1 + U0    (1 plane )
    PIXELFMT_NV12 = KIT_DEFINE_PIXELFOURCC('N', 'V', '1', '2'), //Planar mode: Y + U/V interleaved  (2 planes)
    PIXELFMT_NV21 = KIT_DEFINE_PIXELFOURCC('N', 'V', '2', '1'), //Planar mode: Y + V/U interleaved  (2 planes)
};





//get a human-readable string for a given pixel format
const char* getPixelFmtName(u32 pixel_format);





}; /* namespace kit */

#endif /* _INC__VIDEO_PIXELFMT_HPP */
/******************************************************************************/
/******************************************************************************/
//"2024-11-21\include\kit\_video_Surface.hpp":
#ifndef _INC__VIDEO_SURFACE_HPP
#define _INC__VIDEO_SURFACE_HPP

#include "commondef.hpp"
#include "_video_PixelFmt.hpp"


namespace kit {





class Surface; //forward declaration

//like AudioData, the pointer this returns must have been allocated with
 //memory:alloc specifically (NOT memory::allocSIMD!)
//(also, this doesn't really account for indexed color formats, as while you can specify
 //the palette indexes in the pixel data, the actual pallete will need to be set manually)
typedef void* (*SurfaceLoaderCallback)(const char* filePath, u32& format_out,
                                       u31& width_out, u31& height_out);

typedef void (*SurfaceSaverCallback)(const char* filePath, Surface& surface_in);

//(like AudioData, when saving OR loading, filePath will never be nullptr by the
 //time the callback is invoked, so you don't need to worry about checking for it)



//(not an actual callback, but rather the lack of one)
#define SurfaceLoadBMP ((SurfaceLoaderCallback)nullptr)
#define SurfaceSaveBMP ((SurfaceSaverCallback)nullptr)

void* SurfaceLoadQOI(const char* fP, u32& fmt_o, u31& w_o, u31& h_o);
void  SurfaceSaveQOI(const char* fP, Surface& s_i);

void* SurfaceLoadPNG(const char* fP, u32& fmt_o, u31& w_o, u31& h_o);
void  SurfaceSavePNG(const char* fP, Surface& s_i);





//(specifically, these are the save/load callbacks that come bundled with kit_sdl2,
// though you can in theory make your own for any file format you want! :D)

//currently supported image file formats:
 //.bmp (SurfaceLoadBMP, SurfaceSaveBMP)
 //.qoi (SurfaceLoadQOI, SurfaceSaveQOI)
 //.png (SurfaceLoadPNG, SurfaceSavePNG)

class Window; //forward declaration

class Surface { //16B
  u32          _type;
  bool        _valid = false;
  bool _constructing = true;
  u16     _padding16;
  GenOpqPtr     _opq = nullptr;


  //used by both of the 'load from file' constructors
  void _construct_file(const char* filePath, SurfaceLoaderCallback callback,
                       const char* funcName = nullptr);


public:

  //create a new, completely blank surface
  Surface(u32 width, u32 height, u32 pixel_format);

  //create from another Surface, converting to a new pixel format in the process
  Surface(const Surface& src, u32 pixel_format);

  //create from a Window's surface, converting to a new pixel format in the process
  Surface(const Window& src, u32 pixel_format);

  //create from an image file of a specific file format
   //(may reduce binary size if you only plan to use 1 file type or something)
  Surface(const char* filePath, SurfaceLoaderCallback callback)
  { _construct_file(filePath, callback); }

  //create from an image file of any supported format (.png, .qoi, .bmp)
  Surface(const char* filePath);

  ~Surface();



  //(this will overwrite any file named filePath! make sure to check
   //with fileio::exists() unless you intend to overwrite the previous file)
  void saveImage(const char* filePath, SurfaceSaverCallback callback);



  //"If RLE is enabled, color key and alpha blending blits are much faster,
   //but the surface must be locked before directly accessing the pixels."
  bool                hasRLE();
  bool                hasLockRequirement();
  u32                 getPixelFmt();
  shape::point        getSize(); //{width, height}
  u32                 getBytesPerRow();
  void*               getPixelData();
  void*               getUserdata();
  u32                 getPaletteLen(); //returns 0 if Surface doesn't use a palette
  const colors::ABGR* getPaletteColors(); //returns nullptr if Surface doesn't use a palette
  BlendModesEnum      getBlendMode();
  u8                  getAlphaMod();
  colors::BGR         getColorMod();
  u32                 getColorKey();


  void setRLE(bool enable);
  void setUserdata(void* userdata);
  void setPaletteColors(const colors::ABGR* newColors, u32 numColors, u32 firstColor = 0);
  void setBlendMode(BlendModesEnum blendMode);
  void setAlphaMod(u8 alphaMod);
  void setColorMod(colors::BGR colorMod);
  void setColorKey(bool enable, u32 key);


  u32 mapRGB(colors::BGR inputColor);
  u32 mapRGBA(colors::ABGR inputColor);

  void lock(bool locked = true);
  inline void unlock(){ lock(false); }



  void fillRects(colors::ABGR color, const shape::rect* rects = nullptr, size_t rects_len = 0);


  //w & h of dst are ignored by blit, but not blitScaled
   //(also ignored by blitAt unless scale != 1.0f)
  void blit(Surface& dst_surf, const shape::rect* dst = nullptr,
                               const shape::rect* src = nullptr);

  void blit(Window&  dst_surf, const shape::rect* dst = nullptr,
                               const shape::rect* src = nullptr);


  void blitScaled(Surface& dst_surf, const shape::rect* dst = nullptr,
                                     const shape::rect* src = nullptr);

  void blitScaled(Window&  dst_surf, const shape::rect* dst = nullptr,
                                     const shape::rect* src = nullptr);


  //centered blit (as in, x&y is the center of the blit's destination)
  void blitAt(Surface& dst_surf,  s32 x, s32 y, f32 scale = 1.0f);

  void blitAt(Window&  dst_surf,  s32 x, s32 y, f32 scale = 1.0f);

};





}; /* namespace kit */

#endif /* _INC__VIDEO_SURFACE_HPP */
/******************************************************************************/
/******************************************************************************/
//"2024-11-21\include\kit\_video_Window.hpp":
#ifndef _INC__VIDEO_WINDOW_HPP
#define _INC__VIDEO_WINDOW_HPP

#include "commondef.hpp"
#include "_misc_Mutex.hpp"


namespace kit {





enum WindowPositionEnum {
  WINPOS_UNDEFINED = 0x1FFF0000u,
  WINPOS_CENTERED  = 0x2FFF0000u,
};



enum WindowFlagEnum {
  WINFLAG_FULLSCREEN         = 0x00000001, //fullscreen window
  WINFLAG_OPENGL             = 0x00000002, //window usable with an opengl context
  WINFLAG_HIDDEN             = 0x00000008, //window is not visible
  WINFLAG_BORDERLESS         = 0x00000010, //no window decoration
  WINFLAG_RESIZABLE          = 0x00000020, //window can be resized
  WINFLAG_MINIMIZED          = 0x00000040, //window is minimized
  WINFLAG_MAXIMIZED          = 0x00000080, //window is maximized
  WINFLAG_INPUT_GRABBED      = 0x00000100, //window has grabbed input focus
  WINFLAG_FULLSCREEN_DESKTOP = 0x00001000|WINFLAG_FULLSCREEN, //fs window at desktop resolution
  WINFLAG_VULKAN             = 0x10000000, //window usable with a vulkan instance
};





struct DisplayMode { //16B
  u32 pixelFmt;
  s32 w, h;
  s32 refreshRate;
};





class Surface; //forward declaration

class Window { //40B (24B + sizeof(Mutex))
  u32          _type;
  bool        _valid = false;
  bool _constructing = true;
  u16     _padding16;
  GenOpqPtr     _win = nullptr;
  GenOpqPtr    _surf = nullptr; //window's surface (internal)
  Mutex        _lock; //mostly for mutex'ing surface accesses


public:

  Window(const char* winTitle,
         u31 winWidth, u31 winHeight,
         u32 winFlags = 0,
         s32 winX = WINPOS_UNDEFINED,
         s32 winY = WINPOS_UNDEFINED);

  ~Window();


  inline bool isValid()       { return _valid;        }
  inline bool isConstructing(){ return _constructing; }

  inline void   lock(bool locked = true){ _lock.lock(locked); }
  inline void unlock()                  { _lock.lock(false ); }


  bool         hasSurface();
  u32          getPixelFormat(); //returns pixel format used by window's surface
  u32          getID();
  u32          getDisplayIndex();
  void*        getUserdata(const char* name);
  DisplayMode  getDisplayMode(); //get display mode when visible at fullscreen
  const char*  getTitle();
  shape::point getSize();
  u32          getFlags();
  f32          getOpacity();
  shape::point getMinSize();
  shape::point getMaxSize();
  shape::point getPosition();
  bool         getGrab();
  bool         getKeyboardGrab();
  bool         getMouseGrab();
  shape::rect  getMouseGrabRect();
  f32          getBrightness(); //the window's gamma multiplier, specifically


   //returns previous userdata pointer; name "Window class" is forbidden (as it is used internally)
  void* setUserdata(const char* name, void* userdata);
  void  setDisplayMode(const DisplayMode* mode); //nullptr to use win's dims & desktop's fmt & refresh rate
  void  setTitle(const char* title);
  void  setSize(u31 width, u31 height);
  void  setVisibility(bool visible);
  void  setFullscreen(u32 mode); //0,1,2 = disabled, enabled, enabled @ desktop resolution
  void  setResizable(bool enable);
  void  setBordered(bool enable);
  void  setAlwaysOnTop(bool enable);
  void  setOpacity(f32 opacity); //0.0f -> 1.0f
  void  setMinSize(u31 minWidth, u31 minHeight);
  void  setMaxSize(u31 maxWidth, u31 maxHeight);
  void  setPosition(s32 x, s32 y);
  void  setGrab(bool enable); //also includes keyboard if SDL_HINT_GRAB_KEYBOARD is set (tbd: replace macro name)
  void  setKeyboardGrab(bool enable);
  void  setMouseGrab(bool enable); //confines mouse cursor to window
  void  setMouseGrabRect(const shape::rect* rect = nullptr); //nullptr to use entire window
  void  setBrightness(f32 brightness); //gamma multiplier; 0.0f -> 1.0f
  void  setIcon(Surface& icon);


  void warpMouse(s32 x, s32 y); //teleport cursor, relative to the window's top-left corner
  void minimize();
  void maximize();
  void restore();
  void raise(); //also makes window gain input focus


  //window surface stuff specifically

  //(renewSurface is basically SDL_GetWindowSurface(),
   //but the returned ptr is handled internally)
  bool renewSurface(); //returns false if the Window is invalid
  void destroySurface(); //(surface is destroyed automatically when the Window is destroyed)
  void updateSurface(const shape::rect* rects = nullptr, u31 rects_len = 0);
  //(^^ VV leave rects as nullptr to update/fill whole surface)
  void fillRects(colors::ABGR color, const shape::rect* rects = nullptr, u31 rects_len = 0);

};





//returns window if input is grabbed; nullptr otherwise
Window* getGrabbedWindow();





}; /* namespace kit */

#endif /* _INC__VIDEO_WINDOW_HPP */
/******************************************************************************/
/******************************************************************************/
//"2024-11-21\src\kit_sdl2\_kit_common.hpp":
#ifndef _SRC__KIT_COMMON_HPP
#define _SRC__KIT_COMMON_HPP

/* notes/todo:
throw if trying to create object using an uninitialized subsystem
specify which functions/methods can throw exceptions
when throwing in a constructor, make sure to deallocate any memory

SDL_FlushEvent/Events
SDL_HasEvent/Events
SDL_JoystickEventState
SDL_PeepEvents
SDL_PushEvent
SDL_RegisterEvents
SDL_WaitEvent/EventTimeout

maybe put a mutex on numAllocations

allow user to push their own text errors,

add sampleRate conversion for AudioData that are f32 or f64
also, add 'get' functions for SoundEngine

validity checks only on debug build
  (only make validity checks when i have to as well)

make format conversion helper functions for Surface
make constructor for Surface that doesn't convert formats,
  instead just copying the source format

*/



/*
this could be added to SoundEngine at some point, but this
has the possibility of introducing phase cancellation, so idk


#define convertPan(_pan) CLAMP(_pan, -1.0f, 1.0f)
//#define convertPan(_pan) CLAMP( (_pan+1.0f)*0.5f, 0.0f, 1.0f )

#define sqrt2_inv ( 0.70710678f )

//sort of a work-in-progress
static inline smp_f32s& applyPan(smp_f32s& sample, f32 pan){

  if(pan < 0){
    sample.l += sample.r*(-pan);
    sample.r *= 1.0f+pan;

  } else if(pan > 0){
    sample.r += sample.l*pan;
    sample.l *= 1.0f-pan;

  }

  return sample;
}

*/





#include <SDL2/SDL.h>


#ifdef _DEBUG
#define _log(...) kit_LogInfo(__VA_ARGS__)
#define loghere kit_LogInfo("line %4i: (%s)",__LINE__,__FILE__);
#define _getnumallocs kit_LogInfo("%4i: # OF ALLOCATIONS = %u", __LINE__, (u32)memory::getNumAllocations());

#else
#define _log(...)
#define loghere
#define _getnumallocs

#endif

/*
#define DISABLE_WARNING(_name) _Pragma(#_name)
#define DISABLE_WARNING_PUSH(_name) _Pragma("GCC diagnostic push") DISABLE_WARNING(_name)
#define DISABLE_WARNING_POP _Pragma("GCC diagnostic pop")
*/


#include <kit/all.hpp>





//class type ID macros
#define KIT_OPAQUE_PRESENT (0x80000000)
#define KIT_OPAQUE2_PRESENT (KIT_OPAQUE_PRESENT|0x40000000) //opaque 1 is implied
#define KIT_IS_OPAQUE_PRESENT(_type) ( ((_type)&KIT_OPAQUE_PRESENT) != 0 )
#define KIT_IS_OPAQUE2_PRESENT(_type) ( ((_type)&KIT_OPAQUE2_PRESENT) != 0 )

#define KIT_CLASSTYPE_NULL          (0x0000                      )
#define KIT_CLASSTYPE_MUTEX         (0x0001 | KIT_OPAQUE_PRESENT )
#define KIT_CLASSTYPE_THREAD        (0x0002 | KIT_OPAQUE_PRESENT )
#define KIT_CLASSTYPE_BINARYDATA    (0x0003                      )
#define KIT_CLASSTYPE_FILE          (0x0004 | KIT_OPAQUE_PRESENT )
#define KIT_CLASSTYPE_WINDOW        (0x0005 | KIT_OPAQUE2_PRESENT)
#define KIT_CLASSTYPE_SURFACE       (0x0006 | KIT_OPAQUE_PRESENT )
//#define KIT_CLASSTYPE_TEXTURE       (0x0007 | KIT_OPAQUE_PRESENT )
#define KIT_CLASSTYPE_AUDIODEVICE   (0x0008 | KIT_OPAQUE_PRESENT )
#define KIT_CLASSTYPE_AUDIOSTREAM   (0x0009 | KIT_OPAQUE_PRESENT )
#define KIT_CLASSTYPE_AUDIODATA     (0x000A                      )
#define KIT_CLASSTYPE_SOUNDENGINE   (0x000B | KIT_OPAQUE2_PRESENT)
#define KIT_CLASSTYPE_EVENTWATCH    (0x000C                      )
#define KIT_CLASSTYPE_BFONT_SURFACE (0x000D | KIT_OPAQUE2_PRESENT)





namespace kit {





#define DISABLE_STRICT_ALIASING_WARNING \
  _Pragma("GCC diagnostic push") \
  _Pragma("GCC diagnostic ignored \"-Wstrict-aliasing\"")
#define POP_IGNORED_WARNING \
  _Pragma("GCC diagnostic pop")

#define KIT_GET_CLASS_TYPE(_ptr)         ( ((kit::_commonClassValues*)(_ptr))->type         )
#define KIT_GET_CLASS_VALID(_ptr)        ( ((kit::_commonClassValues*)(_ptr))->valid        )
#define KIT_GET_CLASS_CONSTRUCTING(_ptr) ( ((kit::_commonClassValues*)(_ptr))->constructing )
#define KIT_GET_CLASS_DATA(_ptr)         ( ((kit::_commonClassValues*)(_ptr))->data         )
#define KIT_GET_CLASS_OPAQUE(_ptr)       ( ((kit::_commonClassValues*)(_ptr))->opq          )
#define KIT_GET_CLASS_OPAQUE2(_ptr)      ( ((kit::_commonClassValues*)(_ptr))->opq2         )

#define KIT_IS_CLASS_TYPE(_ptr,_type)   ( KIT_GET_CLASS_TYPE(_ptr) == (_type) )
#define KIT_IS_CLASS_VALID(_ptr)        ( KIT_GET_CLASS_VALID(_ptr) != 0 )
#define KIT_IS_CLASS_CONSTRUCTING(_ptr) ( KIT_GET_CLASS_CONSTRUCTING(_ptr) != 0 )

struct _commonClassValues { //8-24B (depending on KIT_OPAQUE_PRESENT/KIT_OPAQUE2_PRESENT)
  u32          type;
  bool        valid; //'is object fully and successfully constructed?'
  bool constructing; //'is object currently inside constructor?'
  //^^this is useful for if public class functions are called inside the
   //constructor itself, but the valid flag is not set to true yet
  u16          data; //purpose varies by class type; unused by some (or it's split into 2 u8)
  GenOpqPtr     opq; //nonexistent if type lacks the KIT_OPAQUE_PRESENT flag
  GenOpqPtr    opq2; //nonexistent if type lacks the KIT_OPAQUE2_PRESENT flag
};





union Error { //16B
  struct {
    const char* _txt;
    u32   _thread_id;
    bool       _heap;
    u8     _padding8;
    u16   _padding16;
  };

  struct { u64 _0, _1; };


  Error() : _txt(nullptr), _thread_id(0), _heap(false) {}

  Error(const char* txt, bool heap = false)
    : _txt(txt), _thread_id(SDL_GetThreadID(nullptr)), _heap(heap) {}


  inline const char* text(){
    return (_txt != nullptr) ? _txt : "(ERROR TEXT IS NULLPTR)"; }

};





//this limit of 8 might only be a problem if 8 errors
 //are thrown at the same time or something (lol)
#define FSTR_COUNT ((size_t)8)
#define FSTR_LEN   ((size_t)512)

struct _globalStates {
  char fstr_str[FSTR_COUNT][FSTR_LEN];
  s32 fstr_which = 0;

  //normally, the user is warned if the SDL version's patch level
   //is < the one kit_sdl2 was made for, but this can be bypassed
   //(assuming i actually implement something that can enable this flag)
  bool patch_warning_disabled;

  char _; //padding

  u16 CPUCapabilities; //some combination of CPUCapabilityFlagsEnum values

  u64 performanceFreq = 0; //how many performance counter units per second

  //(haptic & sensor subsystems are not included)
  union {
    u64 init_value;
    struct {
      bool timer;
      bool audio;
      bool video;          //auto-inits events
      bool gamecontroller; //auto-inits joystick
      bool joystick;       //auto-inits events
      bool events;
      bool joystick_sdl; //same as events_sdl, except with the joystick subsystem
      bool events_sdl;   //'were events EXPLICITLY initialized? (as in, not auto-init)'
    } init;
  };

  Error* errors     = nullptr;
  size_t errors_len = 0;

  SDL_mutex* lock = nullptr;

};

//found in "kit_func_init-quit.cpp"
extern _globalStates _gl; //gl as in global, not opengl
extern const char _fstr_failure[]; // = "(FSTR FAILED)"

//(will complain about undefined sequencing if you put fstr in a call to fstr,
 //due to the of the "^=" assignment operator)
#define fstr(...) ( \
  (snPrintf(_gl.fstr_str[(_gl.fstr_which=(_gl.fstr_which+1)%FSTR_COUNT)],FSTR_LEN,__VA_ARGS__)>=0) \
    ? (const char*)_gl.fstr_str[_gl.fstr_which] : _fstr_failure \
)

#define   LOCK_GLOBALS() { if(_gl.lock != nullptr) SDL_LockMutex(  _gl.lock); }
#define UNLOCK_GLOBALS() { if(_gl.lock != nullptr) SDL_UnlockMutex(_gl.lock); }





//in _kit_private.cpp:
const char* _pushError(const char* errortext);
bool _freeError(u32 thread_id = 0); //returns true if it found an error to free
void _freeErrors(); //also frees _gl.errors entirely

#define THROW_ERROR(_txt) throw _pushError(_txt)
//fstr itself is not thread safe, so let's lock globals until
 //the result of fstr has been copied to the thread errors list
#define THROW_ERRORF(...) { \
  LOCK_GLOBALS(); \
  const char* _T_EF_long_name_dont_name_anything_else_this = _pushError( fstr(__VA_ARGS__) ); \
  UNLOCK_GLOBALS(); \
  throw _T_EF_long_name_dont_name_anything_else_this; \
}





extern size_t numAllocations;





//100ms
#define FADETOTAL_SEC (0.100f)

//linearly fade over the course of 10ms
#define FADEDELTA_SEC (0.010f)

//the most common audio clipping ends at 10-11ms after unpausing,
 //but i've seen clipping as far as ~450ms after unpausing
#define FADEDELAY_SEC (FADETOTAL_SEC - FADEDELTA_SEC)





#define ERROR_ON_NEGATIVE(_funcname, _var) \
  if((_var) < 0){ THROW_ERROR(_funcname ": " #_var " < 0"); }





}; /* namespace kit */

#include "_kit_opaques.hpp"

#endif /* _SRC__KIT_COMMON_HPP */
/******************************************************************************/
/******************************************************************************/
//"2024-11-21\src\kit_sdl2\_kit_opaques.hpp":
#ifndef _SRC__KIT_OPAQUES_HPP
#define _SRC__KIT_OPAQUES_HPP

//THIS FILE IS NOT TO BE INCLUDED ON ITS OWN,
 //RATHER AS A PART OF "_kit_common.hpp"!!

/*
Opaques are included as follows: (classes without opaques are omitted)
[ ] Mutex
[ ] Thread
[ ] File
[ ] Window
[ ] Surface
[*] AudioDevice
[ ] AudioStream
[*] SoundEngine
*/

namespace kit {





struct _AudioDeviceOpaque {
  AudioDeviceInfo* info_p;

  void*            buffer;
  u32         buffer_size;

  f32           fadeDelta;
  f32          fadeVolume;
  u32           fadeDelay;

  bool            fadeOut; //fade-in otherwise
  bool        noFadeDelay;

  bool            playing;

  u8  _0;
  u32 _1;

};





struct _SoundEngineTrack { //88B
  const AudioDataHeader* audio;

  //time at the point of audio being queued, in milliseconds
  u64                timestamp;

  f64                 position;

  f64                  spd_old;
  f64                  spd_new;
  f64                 spdDelta;

  Stereo_f32           vol_old;
  Stereo_f32           vol_new;
  Stereo_f32          volDelta;
  Stereo_f32         volMaster;

  u16                    loops;
  bool                stopping;

  char             _padding[5];

};





}; /* namespace kit */

#endif /* _SRC__KIT_OPAQUES_HPP */