API "QUICK" REFERENCE
=====================
PARAMETERS
----------
back_art Card Back Artwork, 0 = Use Default
front_art Card Front Artwork, 0 = Use Default
name Suit: sCLUBS sDIAMONDS sHEARTS sSPADES sRED sBLACK
Value: vACE vJACK vQUEEN vKING vJOKER vSPARE 2...10
Eg: vACE|sSPADES 7|sCLUBS sRED|vJOKER 0|sHEARTS
hilite ON OFF
face FACE_UP FACE_DOWN
hide YES NO
nudge NUDGE_OFF NUDGE_UP NUDGE_LEFT
NUDGE_DOWN NUDGE_RIGHT
display STACKED SPREAD_X_N SPREAD_X_O SPREAD_X_W
SPREAD_Y_N SPREAD_Y_O SPREAD_Y_W
PHcard Index into card[] array, normally found with FindCard
ShowPH YES/ NO
method Shuffle: CUT OVERHAND PLAYLIST
RIFFLE FARO_IN FARO_OUT
Sort: BY_NOSORT BY_SCORE
BY_FACE_VALUE BY_SUIT_VALUE
pause TRUE FALSE
(Note: ON/OFF, UP/DOWN, YES/NO, TRUE/FALSE are all the same thing)
FUNCTIONS
---------
_______________________________________________________________________________
FriendlyName RealName return value ( required parameters )
Short description
_______________________________________________________________________________
NewStock NewStock BOOL ( UI8 decks )
Reset the engine; Create new decks; Place them on the STOCK Pile
_______________________________________________________________________________
AddCard CardAdd BOOL ( UI8 deck, UI8 back_art, UI8 front_art,
UI8 name, UI8 score )
Create a new card; Place it on the TOP of the STOCK Pile
_______________________________________________________________________________
SetScore CardSetScore UI16 ( UI8 name, UI8 score )
^
Number of cards updated
Set the score value for all matching cards
_______________________________________________________________________________
FindCard CardFind UI16 ( UI8 deck, UI8 name )
^
0 or pointer to card[] array
Find a specific card
_______________________________________________________________________________
HiliteCard CardHilite BOOL ( UI16 pile, UI16 posn, BOOL hilite )
Hilite a card
_______________________________________________________________________________
TurnCard CardTurn BOOL ( UI16 pile, UI16 posn, BOOL face_up )
Turns over one Card or an entire Pile
_______________________________________________________________________________
Nudge CardNudge BOOL ( UI16 pile, UI16 posn, UI8 nudge )
"Nudge" a card out of line with it's Pile
_______________________________________________________________________________
MoveCard CardMove BOOL ( UI16 fromPile, UI16 fromPosn,
UI16 toPile, UI16 toPosn,
BOOL face, UI8 display )
Move a card from point-A to point-B
_______________________________________________________________________________
PlacePile PilePlace BOOL ( UI16 pile, INT x, INT y )
Set screen position of Pile
_______________________________________________________________________________
HidePile PileHide BOOL ( UI16 pile, BOOL hide )
Hide/UnHide a Pile
_______________________________________________________________________________
SetPH PileSetPH BOOL ( UI16 pile, UI16 PHcard, BOOL showPH )
Set the PlaceHolder card for a Pile
_______________________________________________________________________________
NewPile PileNew UI16 ( UI8 owner, INT x, INT y,
BOOL hide, UI16 PHcard, BOOL showPH )
^
0 or new Pile number
Create a New Pile
_______________________________________________________________________________
GetPile PileGet BOOL ( UI16 pile )
Grab any Pile to 'thisPile'
_______________________________________________________________________________
SavePile PileSave VOID ( VOID )
Save changes to 'thisPile'
_______________________________________________________________________________
SortPile PileSort BOOL ( UI16 pile, UI8 method )
Sort a Pile
_______________________________________________________________________________
ShufflePile PileShuffle BOOL ( UI16 pile, UI8 method )
Shuffle a Pile
_______________________________________________________________________________
ShowPile PileShow BOOL ( UI16 pile, BOOL display )
Display a Pile
_______________________________________________________________________________
DumpPiles PileDump VOID ( CHAR* title, BOOL pause )
Dump all Piles to the debug console
_______________________________________________________________________________
ShowCard CardShow BOOL ( INT x, INT y, UI16 card, BOOL display )
Display a single card
_______________________________________________________________________________
API "FULL" REFERENCE
====================
FUNCTIONS
---------
NewStock (decks)
NewStock (decks)
Desc: Initialises memory, opens a new deck of 52 cards in manufacturers
order, and STACKs them all (NUDGE_OFF) FACE DOWN on the HIDDEN
STOCK Pile under the control of the DEALER.
Prams: UI8 decks Number of standard (52 cards) decks to be created
Return: true -> Decks created successfully
false -> Too many cards; Increase 'MaxCards'
Notes: Before this process does ANYTHING, it cleans up memory.
...So even if it fails, all piles and cards will be destroyed!
NewStock(0); is called as part of the init() function.
AddCard (deck, bart,fart, name, score)
CardAdd (deck, bart,fart, name, score)
Desc: Create a new card and add it to the TOP of the STOCK Pile
Prams: UI8 deck Which deck does the new card belong to
UI8 bart The artwork to use for the BACK of this card
UI8 fart The artwork to use for the FRONT of this card
UI8 name The internal name of the card
UI8 score The score value of the card
Return: bool true -> Card added successfully
false -> Too many cards; increase 'MaxCards'
Notes: Examples card names are: RED|JOKER KING|HEARTS 3|SPADES
You may use '0' for either artwork to use the default artwork
specified by the choice of "card_Deck_???.h"
SetScore (name,score)
CardSetScore (name,score)
Desc: Set the score value for all cards of a specific name
Prams: UI8 name Name of card(s) to be updated
UI8 score New score value
Return: UI16 Number of cards updated
Notes: Examples card names are: RED|JOKER KING|HEARTS 3|SPADES
Any effetced Piles will also have their score updated.
FindCard (deck,name)
CardFind (deck,name)
Desc: Locate a particular card from a particular deck
Prams: UI8 deck Deck from which card comes; 0 means 'any deck'
UI8 name Name of card to locate
Return: UI16 0 -> Card not found
N -> Card ID
Notes: Examples card names are: RED|JOKER KING|HEARTS 3|SPADES
Example code:
/ * He who has the Queen of Spades loses! * /
loser = card[FindCard(0,QUEEN|SPADES)].owner;
HiliteCard (pile,posn, hilite)
CardHilite (pile,posn, hilite)
Desc: Hilite a card - Ie. When it is displayed, invert it.
Prams: UI16 pile The Pile which contains the card
UI16 posn The position of the card within that Pile
bool hilite ON or OFF
Return: true -> Card hilighed successfully
false -> Card not found
Notes: .
TurnCard (pile,posn, face)
CardTurn (pile,posn, face)
Desc: Turns over either one Card or an entire Pile
Prams: UI16 pile The Pile which contains the card
UI16 posn The position of the card within that Pile
'0' means 'all cards in this pile'
bool face FACE_UP or FACE_DOWN
Return: true -> All requested cards turned successfully
false -> Failed to turn one or more cards
Notes: If posn is 0, every card in the Pile is turned to requested state
If posn is non-zero, only the specified card is turned
If you request a while pile is turned and get 'false' back.
You may like to try a GetPile(p) and see if (PileNum>MaxPiles)
after - if so, you have a corrupt pile in your system :(
Nudge (pile,posn, nudge)
CardNudge (pile,posn, nudge)
Desc: "Nudge" a card out of line with it's pile
Prams: UI16 pile The Pile which contains the card
UI16 posn The position of the card within that Pile
UI8 nudge NUDGE_UP or NUDGE_DOWN or
NUDGE_LEFT or NUDGE_RIGHT or NUDGE_OFF
Return: true -> Card Nudged successfully
false -> Card not found
Notes: The Nudge distance is set by either:
'NudgeX' (left/right) or 'NudgeY' (up/down).
MoveCard (fromPile,fromPosn, toPile,toPosn, face,display)
CardMove (fromPile,fromPosn, toPile,toPosn, face,display)
Desc: Move a card from one place to another, and change it's display
status en route.
Prams: UI16 fromPile Which Pile has the card presently
UI16 fromPosn What position is the card within that Pile
UI16 toPile Which Pile should the card end up in
UI16 toPosn What position should the card end up in
bool face FACE_UP or FACE_DOWN
UI8 display SPREAD_X_N or SPREAD_X_O or SPREAD_X_W or
SPREAD_Y_N or SPREAD_Y_O or SPREAD_Y_W or
STACKED
Return: true -> Card moved successfully
false -> Failed to move card
Notes: If fromPile and toPile are the same, the card will be moved to
a new sort position within that Pile.
ALSO, the 'face' and 'display' values are IGNORED, the card's
display status is left untouched.
If the fromPosn is 0, the card taken will be the LAST/TOP card in
the source pile.
If the toPile is 0, a new Pile will be created.
If the toPosn is 0, the card is placed at the END/TOP of the
destination pile
PlacePile (pile, x,y)
PilePlace (pile, x,y)
Desc: Move a Pile to a new screen location
Prams: UI16 pile Pile to be moved
I8 x New X ccord for top left corner of card 1
I8 y New Y ccord for top left corner of card 1
Return: true -> Pile repositioned successfully
false -> Invalid Pile specified
Notes: Piles MAY be placed partially, or entirely off-screen
HidePile (pile, hide)
PileHide (pile, hide)
Desc: Hide/UnHide a Pile
Prams: UI16 pile Pile to be moved
bool hide SHOW or HIDE
Return: true -> Pile (un)hiddent successfully
false -> Invalid Pile specified
Notes: Once Hidden, any call to ShowPile(pile, true) will have no effect
on the display.
If the Pile is currently on display, then Hiding will call
ShowPile(pile,false), to remove the Pile from the display before
setting the Hidden flag.
The process of UnHiding does NOT cause a screen refresh
SetPH (pile, PHcard,showPH)
PileSetPH (pile, PHcard,showPH)
Desc: Set the PlaceHolder card for a pile
Prams: UI16 pile Pile to be marked
UI16 PHcard Card[] number to use as placeholder
Card 0, is a simple outline
bool showPH PlaceHolder Card
ON -> Displayed ...or... OFF -> Unused
Return: true -> Pile PlaceHolder card set successfully
false -> Invalid Pile specified
Notes: If the PlaceHolder is set to OFF, the PlaceHolder-Card is ignored
NewPile (owner, x,y,hide, PHcard,showPH)
PileNew (owner, x,y,hide, PHcard,showPH)
Desc: Create a New Pile & set the basic information
Prams: UI8 owner ID number for the owner of this Pile
I8 x New X ccord for top left corner of card 1
I8 y New Y ccord for top left corner of card 1
bool hide TRUE -> Hidden ...or... FALSE -> Visible
UI16 PHcard Card[] number to use as placeholder
Card 0, is a simple outline
bool showPH PlaceHolder Card
ON -> Displayed ...or... OFF -> Unused
Return: 0 -> Pile FAILED to create; Increase 'MaxPiles'
N -> Pile created successfully. New pile is pile[N]
Notes: The (x,y) coords are always set, but obviously, if the Pile is
Hidden, the coords will mean nothing unless the Pile is UnHidden
If the Pile will NEVER be displayed, I suggest (x,y) = (0,0)
Likewise, the PlaceHolder-Card is always set, but if the
PlaceHolder is OFF then it will go unused unless the PlaceHolder
is turned on.
If the PlaceHolder will NEVER be displayed, I suggest
PlaceHolder-Card = 0
GetPile (pile)
PileGet (pile)
Desc: Grab a single Pile of cards to 'thisPile' for manipulation
Cards are retrieved in Position order.
Prams: UI16 pile Pile to be retrieved
Return: true -> Pile retrieved successfully
false -> Non-existent or Corrupt Pile
Notes: If a corrupt pile is retrieved (this should never happen) then
'PileNum' will be set to the requested pile number + 'MaxPiles'
Example Code
""""""""""""
UI16 pile = 7;
bool success = GetPile(pile);
if (!success)
{
if (PileNum==0)
printf("Pile not found, `thisPile` is now empty.");
else if (PileNum>MaxPiles)
printf("Pile %d retrieved, but is corrupt", PileNum-MaxPiles);
else
printf("This should never happen!");
}
else
printf("Pile %d retrived okay", PileNum);
SavePile ()
PileSave ()
Desc: Save the current positions of all cards in 'thisPile' back to the
main card[] array
Prams: none
Return: nothing
Notes: This is only really called internally, you should never need to
use it, but as it had to be here, I thought I might as well open
it up to the interface
SortPile (pile, method)
PileSort (pile, method)
Desc: Sorts a Pile using the requested method
Prams: UI16 pile Pile to be retrieved
UI8 method BY_NOSORT or BY_SCORE or
BY_FACE_VALUE or BY_SUIT_VALUE
Return: true -> Pile sorted successfully
false -> Invalid Pile or Unknown Method
Notes: BY_NOSORT Rather pointless, only really for test purposes.
BY_FACE_VALUE A, 2, 3, ..., J, Q, K, Joker, Spare
BY_SUIT_VALUE Suits grouped; Card within suits in face order
Suit sort order is defined in the bc_cards.h
BY_SCORE Score value assigned to the cards
You may want to sort BY_FACE_VALUE before you sort
BY_SCORE, to make sure that all cards with the same
score are grouped by Face Value.
ShufflePile (pile, method)
PileShuffle (pile, method)
Desc: Shuffles a Pile of cards using the requested method
Prams: UI16 pile Pile to be shuffled
UI8 method CUT or OVERHAND or PLAYLIST or
RIFFLE or FARO_IN or FARO_OUT
Return: true -> Pile shuffled successfully
false -> Invalid Pile specified
Notes: This is probably the cleverestist chunk the code.
Shuffle() will happily shuffle piles of 0, 1, 2 or more cards.
FARO_IN A perfect 1:1 interleaving on the cards
Bottom card moves
FARO_OUT A perfect 1:1 interleaving on the cards
Bottom card remains on the bottom
An ordinary deck of 52 cards is returned to it's original order
after 52 FARO_IN shuffles, but after only 8 FARO_OUT shuffles!
http://mathworld.wolfram.com/RiffleShuffle.html
RIFFLE Simulate a human Riffle Shuffle
The cut is made randomly between 47.5%...62.5%, that's
1/2 +/- 1/8. Dropping from a random hand first,
1...3 cards are dropped and then the hand alternates
until all cards are done.
OVERHAND Simulate a human Overhand Shuffle
The cut is made such that 40%...80% of the cards are
removed from the bottom of the deck.
Then an amount of cards equal to 10%...50% of that
initial cut are taken from top the removed cards and
placed on top of the original cards.
This is repeated until all cards are done.
If the the movement of the cards leaves <10% in the
removed pile, then there is a 50:50 chance that they
will be added to the last drop.
CUT This is a stright cut of the deck randomly between
25%...75%
PLAYLIST This uses the same algorithm as the Rockbox PlayList
shuffler.
I wanted lots of shuffles, and this one is cute :)
ShowPile(pile, display)
PileShow(pile, display)
Desc: Display a pile of cards
Prams: UI16 pile Pile to be displayed-on/removed-from display
bool display true->display or false->remove
Return: true -> Pile displayed/removed successfully
false -> Invalid Pile specified or
Pile contains an invalid card
Notes: If the pile is hidden with HidePile(pile,true), then ShowPile will
perform no action, but will return true.
If a pile which is curently being displayed is hidden with
HidePile(pile,true), then ShowPile will be called automatically
so as to remove the Pile from the display.
A Pile should never contain an invalid card. If this does happen
then display of the pile will abort when the illegal card is
encountered.
DumpPiles(title, pause)
PileDump(title, pause)
Desc: Dumps all Piles to the debug console
Prams: char* title Some text to help you identify the caller
bool pause true -> Wait for a key stroke before returning
Return: Nothing
Notes: This is only for use in the simulator when debugging your game.
ShowCard(x,y, card, display)
CardShow(x,y, card, display)
Desc: Show a single card on the screen
Prams: I8 x New X ccord for top left corner of card 1
I8 y New Y ccord for top left corner of card 1
UI16 card Index into card[] array
bool display true->display or false->remove
Return: true -> Card displayed/cleared successfully
false -> Card does not exist, or illegal nudge type specified,
or Unknown Deck design
Notes: This will generally be called only by ShowPile()
Full clipping is supported via the bc_gfx() library
ShowCard() calls CardFace()
...this procedure is unique for any given set of cards
bool card_init(
|