.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 June McEnroe Aq Mt june@causal.agency