diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..fbc3629 --- /dev/null +++ b/.gitattributes @@ -0,0 +1,3 @@ +*.DSK binary +*.dsk binary +*.png binary diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..e1004ac --- /dev/null +++ b/.gitignore @@ -0,0 +1,18 @@ +.DS_Store +._* +__pycache__/ +*.pyc +*.o +*.a +*.bin +*.map +*.lst +*.link +*.i +*.hex +*.dsk +*.DSK +!/CardGame.DSK +build/ +.build/ +.cache/ diff --git a/CardGame.DSK b/CardGame.DSK new file mode 100644 index 0000000..0a84846 Binary files /dev/null and b/CardGame.DSK differ diff --git a/README.md b/README.md index 279a27b..4cfcb99 100644 --- a/README.md +++ b/README.md @@ -1,115 +1,48 @@ -CardGame -======== +# CardGame graphics demo -By Pierre Sarrazin (). +A playing-card and PMODE 4 graphics library by **Pierre Sarrazin**, with its +original demonstration program. This repository contains upstream version +**0.1.15** with a VCC Plus project and disk launcher. -This library is in the public domain. +![CardGame running in VCC Plus, displaying all four card suits](docs/screenshots/running.png) -It is a C library that offers a PMODE 4 game library that can display -playing cards. It targets the Tandy Color Computer but should also work -on the Dragon. Most of the features should also work on CoCo-based -versions of OS-9. +## Download and run +Download [CardGame.DSK](CardGame.DSK). Mount a writable copy in drive 0 of a +**512 KB CoCo 3 / 6809 / Disk BASIC** machine, then type: -# OS-9 Support +```basic +LOADM"CARDGAME":EXEC +``` -OS-9 was suspended with version 0.1.11 but has been restored with version 0.1.12. +The demonstration displays a complete four-suit deck and the prompt +**PRESS BREAK TO QUIT**. Use the CoCo Break key to leave the demonstration. -Note that the sound features of this version of the library are not supported under OS-9. +## Build in VCC Plus -To compile with OS-9, pass TARGET=os9 to make. +1. Open this repository’s root folder in **Develop → C Development → Open**. +2. Select **Release**, then choose **Build Disk**. +3. Use **Show Build Products** to find `CardGame.DSK` and `cardgame.bin` in the + build snapshot. Launch the disk with the command above. -The "cardgame" demo program MUST be run from a 32x16 VDG terminal. -Use the Clear key to find one. -If none exists, create one with the "shell i=/v1" command, then use Clear to find it. +The project selects `VCCPlus.mk`, which includes the original `Makefile` and adds +the `vccplus-disk` packaging target. It uses VCC Plus’s bundled CMOC and disk tools. -The "os9timer" demo program can be run from any terminal. +The disk build and illustrated run were verified through the public MCP +interface in **VCC Plus 3.5.0 build 43**, using the configuration above. +[Validation details](docs/VALIDATION.md) describe the checked behavior and limits. -There is no "beep" demo program for OS-9. +## Original source +- Author: [Pierre Sarrazin](http://sarrazip.com/). +- [CMOC project index](http://sarrazip.com/dev/cmoc.html). +- [Cardgame 0.1.15 source archive](http://sarrazip.com/dev/cardgame-0.1.15.tar.gz). +- Archive SHA-256: `ca706dddd96fec63b829f8958c2e47485b0e1166129d45fda0b6369404c1bb54`. -# Adapting to version 0.1.11 +The [original README](docs/UPSTREAM_README.md) and source notices are preserved. +See [source provenance](docs/PROVENANCE.md) for the import and integration history. -openPMode4GameScreenMode() and closePMode4GameScreenMode() have been renamed to -openPMode4Game() and closePMode4Game() because the latter does not restore -the screen mode anymore. It cannot know in which mode the screen was initially. +## License -openPMode4Game() does not call resetPalette() anymore, which assumed that Basic -was present. That call was made only when TRUE was passed for emulatePMode4OnCoCo3. -Now, in this case, only palette slots 0..3 are initialized. - -openCardGameScreenMode() and closeCardGameScreenMode() have been renamed to -openCardGame() and closeCardGame() for similar reasons. - -restoreOriginalTextMode() has been removed from the interface, since it relied -on Basic. The program must restore the text mode itself, if needed. - -Under OS-9, this can be done this way: - - putstr("\x12\x0E", 2); - -Under the native environment: - - screen(0, 0); - -Function waitForKeyWithAnimatedCursor() and readLineFromKeyboard() must now -be passed a callback to a function that returns a timer value that increments -60 times per second. See pmode4game.h for details. - - -# Text font - -The text font supports ASCII characters 32 to 96 inclusively. It does not -support lower-case letters. - -The font is 8 bits wide, which makes it relatively efficient to write. - -See 8-bit-wide-font.h and 8-bit-wide-font.c. - - -# Version history - - 0.1.0 - 2015-08-12 - First public release. - 0.1.1 - 2016-03-12 - New #defines. New function drawFaceDownCard(). - 0.1.2 - 2016-03-25 - setConsoleOutHook() and resetConsoleOutHook() now taken - from . - 0.1.3 - 2017-12-01 - openCardGameScreenMode() now optionally emulates PMODE 4 - in a CoCo 3 mode to approximate the artifact colors. - Assumes RGB mode. Adapted to compile in linker mode. - 0.1.4 - 2018-04-03 - Adaptation to CMOC 0.1.51 (const). - 0.1.5 - 2018-08-04 - Added square brackets and backslash to 8-bit-wide-font.c. - Added sound routines. - 0.1.6 - 2018-09-20 - Adapted to CMOC 0.1.53. - Sound functions now declared by cardgame.h. beep.h now obsolete. - 0.1.7 - 2018-10-04 - Fixed openPMode4GameScreenMode() re: CoCo 3 mode. - 0.1.8 - 2018-11-25 - Now compilable for the Dragon (make TARGET=dragon). - 0.1.9 - 2019-06-03 - OS-9 supported, except for sound. - 0.1.10 - 2020-06-28 - Functions added: drawCharWithoutMovingCursor(), moveCursorLeft(), - invertCharAtCursor(), waitForKeyWithAnimatedCursor(), readLineFromKeyboard(). - Removed PMODE4_PAGE0 and PMODE4_PAGE1: use - (byte *) (((word) * (byte *) 0x00BC) << 8) - to get the ECB PMODE buffer address instead. - 0.1.11 - 2023-06-27 - The library does not assume the presence of Basic anymore. - See section "Adapting to version 0.1.11" for details. - OS-9 support is suspended [restored with 0.1.12]. - 0.1.12 - 2024-06-08 - Added setScreenBuffer2(), which allows to omit showing the screen. - Put several functions in individual C files to help reduce the size - of programs that do not use all functions of this library. - Added os9timer-demo.c to the archive generated by 'make dist'. - 0.1.13 - 2025-11-16 Added drawCompiledCard2(), which supports drawing the suit a little - higher or lower than the default, and supports only drawing the top - of a card, by specifying the number of pixel rows to draw. - Fixed drawCompiledPixMap() so that its inline assembly does not - refer to any global C variable in the code section that uses - the Y register. (That register is used under OS-9 to point to - the current process's global variables segment.) The old code - was not defective but its structure was error prone. - Added getCursor(), which returns the current position of the cursor. - Removed runPMode4GameDoubleBufferLoop(), which is obsolete. - 0.1.14 - 2026-02-05 Added setInvertedColorsParameters(), which determines how caracters - are rendered in inverted colors mode, from parameters drawRowOverGlyph - and drawColumnAtRightOfGlyph. - Added makeSpacesTransparent(), which determines if space characters - are drawn (the pixels take the background color) or not (the pixels - remain unmodified). - 0.1.15 - 2026-09-06 Added ^, _ and ` to the 8-bit-wide font. +The upstream library and demonstration code are in the public domain. +Original file-level author notices are retained. diff --git a/VCCPlus.mk b/VCCPlus.mk new file mode 100644 index 0000000..3d99ed4 --- /dev/null +++ b/VCCPlus.mk @@ -0,0 +1,9 @@ +# VCC Plus disk packaging; the upstream build rules remain in Makefile. +include Makefile + +.PHONY: vccplus-disk +vccplus-disk: CardGame.DSK + +CardGame.DSK: cardgame.bin + perl -e 'print chr(255) x (35*18*256)' > $@ + writecocofile $@ cardgame.bin diff --git a/docs/PROVENANCE.md b/docs/PROVENANCE.md new file mode 100644 index 0000000..404975e --- /dev/null +++ b/docs/PROVENANCE.md @@ -0,0 +1,35 @@ +# Source provenance + +## Original package + +- Original author: **Pierre Sarrazin**. +- Package: **Cardgame 0.1.15**. +- [Author index](http://sarrazip.com/dev/cmoc.html). +- [Source archive](http://sarrazip.com/dev/cardgame-0.1.15.tar.gz). +- Archive SHA-256: `ca706dddd96fec63b829f8958c2e47485b0e1166129d45fda0b6369404c1bb54`. +- Upstream terms: public-domain library/demo, with original file-level notices. + +The VCCPlus Cardgame source manifest also records the historical author-hosted +URL `http://gvlsywt.cluster051.hosting.ovh.net/dev/cardgame-0.1.15.tar.gz` with +the same SHA-256. A checksum identifies the imported bytes; it is not an +independent authenticity guarantee. + +## Git history and VCC Plus integration + +The original distribution was a source archive. The initial commit, +`d3a54e24eef8b1cb6f8427cc1d8968504d403b48`, imports its 39 original regular files before integration. +The original README is also preserved byte-for-byte in `UPSTREAM_README.md`. +Original author notices remain in the source. + +The integration leaves the library/demo C/header files and upstream `Makefile` +unchanged. `VCCPlus.mk` includes that Makefile and adds the `vccplus-disk` target, +which packages `cardgame.bin` into `CardGame.DSK`. The VCC Plus project selects +that disk target and `LOADM"CARDGAME":EXEC` launcher. The top-level disk is an +intentional playable artifact, while incidental objects/libraries/maps are +excluded through `.gitignore`. + +The new public README, actual framebuffer screenshot and +[validation record](VALIDATION.md) describe the installed build-43 public MCP +build and displayed four-suit deck. Source import, integration, validation and +later hosting/avatar changes remain separate events. The original distribution +archive and earlier local project were not modified by this import. diff --git a/docs/UPSTREAM_README.md b/docs/UPSTREAM_README.md new file mode 100644 index 0000000..279a27b --- /dev/null +++ b/docs/UPSTREAM_README.md @@ -0,0 +1,115 @@ +CardGame +======== + +By Pierre Sarrazin (). + +This library is in the public domain. + +It is a C library that offers a PMODE 4 game library that can display +playing cards. It targets the Tandy Color Computer but should also work +on the Dragon. Most of the features should also work on CoCo-based +versions of OS-9. + + +# OS-9 Support + +OS-9 was suspended with version 0.1.11 but has been restored with version 0.1.12. + +Note that the sound features of this version of the library are not supported under OS-9. + +To compile with OS-9, pass TARGET=os9 to make. + +The "cardgame" demo program MUST be run from a 32x16 VDG terminal. +Use the Clear key to find one. +If none exists, create one with the "shell i=/v1" command, then use Clear to find it. + +The "os9timer" demo program can be run from any terminal. + +There is no "beep" demo program for OS-9. + + +# Adapting to version 0.1.11 + +openPMode4GameScreenMode() and closePMode4GameScreenMode() have been renamed to +openPMode4Game() and closePMode4Game() because the latter does not restore +the screen mode anymore. It cannot know in which mode the screen was initially. + +openPMode4Game() does not call resetPalette() anymore, which assumed that Basic +was present. That call was made only when TRUE was passed for emulatePMode4OnCoCo3. +Now, in this case, only palette slots 0..3 are initialized. + +openCardGameScreenMode() and closeCardGameScreenMode() have been renamed to +openCardGame() and closeCardGame() for similar reasons. + +restoreOriginalTextMode() has been removed from the interface, since it relied +on Basic. The program must restore the text mode itself, if needed. + +Under OS-9, this can be done this way: + + putstr("\x12\x0E", 2); + +Under the native environment: + + screen(0, 0); + +Function waitForKeyWithAnimatedCursor() and readLineFromKeyboard() must now +be passed a callback to a function that returns a timer value that increments +60 times per second. See pmode4game.h for details. + + +# Text font + +The text font supports ASCII characters 32 to 96 inclusively. It does not +support lower-case letters. + +The font is 8 bits wide, which makes it relatively efficient to write. + +See 8-bit-wide-font.h and 8-bit-wide-font.c. + + +# Version history + + 0.1.0 - 2015-08-12 - First public release. + 0.1.1 - 2016-03-12 - New #defines. New function drawFaceDownCard(). + 0.1.2 - 2016-03-25 - setConsoleOutHook() and resetConsoleOutHook() now taken + from . + 0.1.3 - 2017-12-01 - openCardGameScreenMode() now optionally emulates PMODE 4 + in a CoCo 3 mode to approximate the artifact colors. + Assumes RGB mode. Adapted to compile in linker mode. + 0.1.4 - 2018-04-03 - Adaptation to CMOC 0.1.51 (const). + 0.1.5 - 2018-08-04 - Added square brackets and backslash to 8-bit-wide-font.c. + Added sound routines. + 0.1.6 - 2018-09-20 - Adapted to CMOC 0.1.53. + Sound functions now declared by cardgame.h. beep.h now obsolete. + 0.1.7 - 2018-10-04 - Fixed openPMode4GameScreenMode() re: CoCo 3 mode. + 0.1.8 - 2018-11-25 - Now compilable for the Dragon (make TARGET=dragon). + 0.1.9 - 2019-06-03 - OS-9 supported, except for sound. + 0.1.10 - 2020-06-28 - Functions added: drawCharWithoutMovingCursor(), moveCursorLeft(), + invertCharAtCursor(), waitForKeyWithAnimatedCursor(), readLineFromKeyboard(). + Removed PMODE4_PAGE0 and PMODE4_PAGE1: use + (byte *) (((word) * (byte *) 0x00BC) << 8) + to get the ECB PMODE buffer address instead. + 0.1.11 - 2023-06-27 - The library does not assume the presence of Basic anymore. + See section "Adapting to version 0.1.11" for details. + OS-9 support is suspended [restored with 0.1.12]. + 0.1.12 - 2024-06-08 - Added setScreenBuffer2(), which allows to omit showing the screen. + Put several functions in individual C files to help reduce the size + of programs that do not use all functions of this library. + Added os9timer-demo.c to the archive generated by 'make dist'. + 0.1.13 - 2025-11-16 Added drawCompiledCard2(), which supports drawing the suit a little + higher or lower than the default, and supports only drawing the top + of a card, by specifying the number of pixel rows to draw. + Fixed drawCompiledPixMap() so that its inline assembly does not + refer to any global C variable in the code section that uses + the Y register. (That register is used under OS-9 to point to + the current process's global variables segment.) The old code + was not defective but its structure was error prone. + Added getCursor(), which returns the current position of the cursor. + Removed runPMode4GameDoubleBufferLoop(), which is obsolete. + 0.1.14 - 2026-02-05 Added setInvertedColorsParameters(), which determines how caracters + are rendered in inverted colors mode, from parameters drawRowOverGlyph + and drawColumnAtRightOfGlyph. + Added makeSpacesTransparent(), which determines if space characters + are drawn (the pixels take the background color) or not (the pixels + remain unmodified). + 0.1.15 - 2026-09-06 Added ^, _ and ` to the 8-bit-wide font. diff --git a/docs/VALIDATION.md b/docs/VALIDATION.md new file mode 100644 index 0000000..a09c171 --- /dev/null +++ b/docs/VALIDATION.md @@ -0,0 +1,54 @@ +# CardGame installed-app validation + +Verified **November 9, 2026** through the installed VCC Plus public MCP build +and disposable-playtest interface. This records the supplied graphics demo; +it is not a complete library regression suite or card-game playthrough. + +## Configuration + +- VCC Plus **3.5.0 build 43** with bundled CMOC/Make/disk tools. +- An isolated native copy of the installed app preserved the active CoCoMan + workspace. Its emulator code was unchanged; the bundle identity was changed + and the copy was ad-hoc signed for isolation. +- **Release**, **512 KB RAM**, **MC6809**, **Disk BASIC**. +- Approved Make recipe: `VCCPlus.mk`, including upstream `Makefile`. +- Public build action: `disk`; declared target: `vccplus-disk`. +- Launch command: `LOADM"CARDGAME":EXEC`. + +## Build evidence + +- Project ID: `7E8305F0-FF04-46E8-A991-7E86A76F372F`; source revision: `0`. +- Recipe ID: `d0430e152313d2964ea1f3a601b2e0062cb10119c9f5084ed6c717f5bed995f0`. +- Build ID: `47760045-032C-490F-AA75-1B29BB368D37`; result: **succeeded**. +- Artifact ID: `E27DB402-DF5B-49C4-9CFC-63E1F5D4632E`. +- `cardgame.bin`: **6,190 bytes**; SHA-256 + `35a87b7f8027b2343c533005c0f388ee47ee7b17ef88b9405aeaad9eaa961688`. +- Delivered `CardGame.DSK`: **161,280 bytes**; SHA-256 + `584df711fc5814cadaf958c772c57cedc6aeaac39731fe9095ebb43ee000c475`. + +Compilation, library creation, linking and disk packaging completed. The +available build log contained no compiler warnings, and the build receipt +reported no diagnostics. Original library/demo source and Makefile were unchanged. + +## Execution and screenshot + +MCP-owned run `1BC4F286-AFA5-4F93-A888-B06BDE0A4F8D` displayed the complete +four-suit deck and **PRESS BREAK TO QUIT** prompt. The actual framebuffer was +captured after **1,096 emulated video fields**, with **6,912 bytes read from +disk**, zero disk writes and the same disk SHA-256 as the verified artifact. +The run was then stopped and its test disk retained by VCC Plus. + +[The screenshot](screenshots/running.png) is the actual **640 × 480** framebuffer +returned by MCP. SHA-256: +`5968f09c6ca539b250cf6589e67263d2bb3c07d573c3acaf7c99dd7236af6f67`. +It is not an illustration or a capture of an older supplied disk. + +The capture shows the quit instruction. Sending Break and checking the return +to BASIC were not separately tested; the owned run was stopped after capture. + +## Scope + +This establishes the specified fresh Release disk build and displayed demo. +It does not claim all library APIs, OS-9/Dragon targets, HD6309 execution, +Intel/Rosetta qualification, physical CoCo hardware, audible audio or a full +card-game test. No private connection grant or raw host log is included. diff --git a/docs/screenshots/running.png b/docs/screenshots/running.png new file mode 100644 index 0000000..125bdc9 Binary files /dev/null and b/docs/screenshots/running.png differ diff --git a/vccplus-project.json b/vccplus-project.json new file mode 100644 index 0000000..32d1073 --- /dev/null +++ b/vccplus-project.json @@ -0,0 +1,25 @@ +{ + "entrySource": "cardgame-demo.c", + "makefile": "VCCPlus.mk", + "buildTarget": "all", + "binary": "cardgame.bin", + "launchMode": "disk", + "configurations": [ + { + "name": "Debug", + "makeArguments": [ + "INTERMEDIATE=--intermediate" + ] + }, + { + "name": "Release", + "makeArguments": [] + } + ], + "jobs": 4, + "diskTarget": "vccplus-disk", + "diskImage": "CardGame.DSK", + "launchCommands": [ + "LOADM\"CARDGAME\":EXEC" + ] +}