Browse Source

Document cards library

master
Causal Agent 4 months ago
parent
commit
18995f4fea
Signed by: Curtis McEnroe <june@causal.agency> GPG Key ID: CEA2F97ADCFCD77C
3 changed files with 221 additions and 4 deletions
  1. 217
    0
      cards.3
  2. 2
    2
      cards.c
  3. 2
    2
      cards.h

+ 217
- 0
cards.3 View File

@@ -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

+ 2
- 2
cards.c View File

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

+ 2
- 2
cards.h View File

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


Loading…
Cancel
Save