Add README

2 files changed, 234 insertions, 0 deletions

diff --git a/Makefile b/Makefile
index 488245d..b8db2fb 100644
--- a/Makefile
+++ b/Makefile
@@ -15,3 +15,6 @@ cards.o dump.o example.o: cards.h
 
 clean:
 	rm -f ${BINS} *.o *.bmp
+
+README.3: cards.3
+	ln cards.3 README.3
diff --git a/README.3 b/README.3
new file mode 100644
index 0000000..26c142c
--- /dev/null
+++ b/README.3
@@ -0,0 +1,231 @@
+.Dd August 22, 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 FILES
+The
+.Lk https://code.causal.agency/june/cards.dll "cards.dll repository"
+contains various versions
+of the files
+.Pa CARDS.DLL ,
+.Pa FREECELL.EXE
+and
+.Pa SOL.EXE .
+.
+.Sh EXAMPLES
+See
+.Pa example.c .
+.
+.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