Document cards library

3 files changed, 221 insertions, 4 deletions

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
 );