diff options
| -rw-r--r-- | Makefile | 3 | ||||
| -rw-r--r-- | README.3 | 231 |
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 |