From 18995f4fea5ebdbbcea44d050b83e9e1949e3eea Mon Sep 17 00:00:00 2001 From: Curtis McEnroe Date: Fri, 29 Mar 2019 00:07:30 -0400 Subject: Document cards library --- cards.3 | 217 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ cards.c | 4 +- cards.h | 4 +- 3 files changed, 221 insertions(+), 4 deletions(-) create mode 100644 cards.3 diff --git a/cards.3 b/cards.3 new file mode 100644 index 0000000..7882756 --- /dev/null +++ b/cards.3 @@ -0,0 +1,217 @@ +.Dd March 28, 2019 +.Dt CARDS 3 +.Os +. +.Sh NAME +.Nm Cards_LoadCards , +.Nm Cards_LoadFreeCell , +.Nm Cards_InvertSurface +.Nd bitmap resource loader +. +.Sh SYNOPSIS +.In cards.h +. +.Ft int +.Fo Cards_LoadCards +.Fa "SDL_Surface *surfaces[]" +.Fa "size_t count" +.Fa "SDL_RWops *rw" +.Fa "enum Cards_Flag flags" +.Fc +. +.Ft int +.Fo Cards_LoadFreeCell +.Fa "SDL_Surface *surfaces[]" +.Fa "size_t count" +.Fa "SDL_RWops *rw" +.Fa "enum Cards_Flag flags" +.Fc +. +.Ft int +.Fn Cards_InvertSurface "SDL_Surface *surface" +. +.Sh DESCRIPTION +.Fn Cards_LoadCards +and +.Fn Cards_LoadFreeCell +load bitmap resources +into an array of +.Fa count +surfaces. +Resources can be loaded +from 16-bit NE executables +or from 32-bit PE executables. +. +.Pp +.Fn Cards_LoadCards +loads card bitmaps from a +.Pa CARDS.DLL +or Windows 3.0 +.Pa SOL.EXE +file +.Fa rw . +. +.Pp +Indices of loaded surfaces +are defined by the following: +.Bl -tag -width Ds -offset indent +.It Suit +.Dv Cards_Club , +.Dv Cards_Diamond , +.Dv Cards_Heart , +.Dv Cards_Spade . +.It Rank +.Dv Cards_A , +.Dv Cards_2 , +.Dv Cards_3 , +.Dv Cards_4 , +.Dv Cards_5 , +.Dv Cards_6 , +.Dv Cards_7 , +.Dv Cards_8 , +.Dv Cards_9 , +.Dv Cards_10 , +.Dv Cards_J , +.Dv Cards_Q , +.Dv Cards_K . +.It Back +.Dv Cards_Back1 , +.Dv Cards_Back2 , +.Dv Cards_Back3 , +.Dv Cards_Back4 , +.Dv Cards_Back5 , +.Dv Cards_Back6 , +.Dv Cards_Back7 , +.Dv Cards_Back8 , +.Dv Cards_Back9 , +.Dv Cards_Back10 , +.Dv Cards_Back11 , +.Dv Cards_Back12 . +.It Other +.Dv Cards_Empty , +.Dv Cards_X , +.Dv Cards_O . +.El +. +.Pp +Where suit and rank constants +are added together to form an index. +Note that there are gaps in the indices +and some surface pointers will be set to +.Dv NULL . +The maximum number of surfaces +is defined by +.Dv Cards_CardCount . +. +.Pp +The dimensions of the loaded surfaces +are defined by +.Dv Cards_CardWidth +and +.Dv Cards_CardHeight . +. +.Pp +.Fn Cards_LoadCards +accepts the following flags: +.Bl -tag -width "Cards_BlackBorders" -offset indent +.It Dv Cards_ColorKey +Use color key transparency for the +.Dv Cards_Empty , +.Dv Cards_X +and +.Dv Cards_O +surfaces. +.It Dv Cards_AlphaCorners +Make the rounded card corners transparent. +.It Dv Cards_BlackBorders +Make all card borders black. +.El +. +.Pp +.Fn Cards_LoadFreeCell +loads bitmaps from a +.Pa FREECELL.EXE +file +.Fa rw . +. +.Pp +Indices of loaded surfaces +are defined by +.Dv Cards_KingRight , +.Dv Cards_KingLeft +and +.Dv Cards_KingWin . +Note that there are gaps in the indices +and some surface pointers will be set to +.Dv NULL . +The maximum number of surfaces +is defined by +.Dv Cards_FreeCellCount . +. +.Pp +The dimensions of the loaded surfaces +are defined by +.Dv Cards_KingWidth +and +.Dv Cards_KingHeight . +. +.Pp +.Fn Cards_LoadFreeCell +accepts the following flags: +.Bl -tag -width "Cards_ColorKey" -offset indent +.It Dv Cards_ColorKey +Use color key transparency. +.El +. +.Pp +.Fn Cards_InvertSurface +inverts the colors of a surface loaded by +.Fn Cards_LoadCards . +. +.Sh RETURN VALUES +Upon successful completion, +the value 0 is returned; +otherwise the value -1 is returned. +. +.Sh ERRORS +Error messages are set with +.Fn SDL_SetError +and can be retrieved with +.Fn SDL_GetError . +. +.Pp +.Fn Cards_LoadCards +and +.Fn Cards_LoadFreeCell +may fail for the following reasons: +any +.Vt SDL_RWops +or +.Vt SDL_Surface +error; +invalid MZ, NE or PE signatures; +missing resource table; +invalid resource hierarchy; +missing resource. +. +.Pp +.Fn Cards_InvertSurface +may fail for any +.Vt SDL_Surface +error +or if the surface format is not supported. +. +.Sh STANDARDS +.Bl -item +.It +The New Executable format, +documented in +.Pa exefmt.txt . +.It +The Portable Executable format, +documented at +.Lk https://docs.microsoft.com/en-us/windows/desktop/Debug/pe-format . +.El +. +.Sh AUTHORS +.An C. McEnroe Aq Mt june@causal.agency diff --git a/cards.c b/cards.c index fd108b9..9e92aa9 100644 --- a/cards.c +++ b/cards.c @@ -337,7 +337,7 @@ checkRange(SDL_Surface **surfaces, size_t count, size_t a, size_t b) { int Cards_LoadCards( - SDL_Surface **surfaces, size_t count, + SDL_Surface *surfaces[], size_t count, SDL_RWops *rw, enum Cards_Flag flags ) { memset(surfaces, 0, sizeof(*surfaces) * count); @@ -358,7 +358,7 @@ Cards_LoadCards( int Cards_LoadFreeCell( - SDL_Surface **surfaces, size_t count, + SDL_Surface *surfaces[], size_t count, SDL_RWops *rw, enum Cards_Flag flags ) { memset(surfaces, 0, sizeof(*surfaces) * count); diff --git a/cards.h b/cards.h index 845b97b..9625cb8 100644 --- a/cards.h +++ b/cards.h @@ -65,13 +65,13 @@ enum Cards_Flag { int Cards_LoadCards( - SDL_Surface **surfaces, size_t count, + SDL_Surface *surfaces[], size_t count, SDL_RWops *rw, enum Cards_Flag flags ); int Cards_LoadFreeCell( - SDL_Surface **surfaces, size_t count, + SDL_Surface *surfaces[], size_t count, SDL_RWops *rw, enum Cards_Flag flags ); -- cgit 1.4.1