From 2682bc5d1d864341aaeb42a449db73c3ecd16d70 Mon Sep 17 00:00:00 2001 From: "Juan J. Martinez" Date: Wed, 30 Dec 2020 19:07:31 +0000 Subject: Initial import --- docs/Makefile | 18 ++++++++++++ docs/footer.md | 3 ++ docs/monokai.css | 73 +++++++++++++++++++++++++++++++++++++++++++++++++ docs/mplayer.md | 83 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ docs/spman.md | 36 ++++++++++++++++++++++++ docs/water.css | 2 ++ 6 files changed, 215 insertions(+) create mode 100644 docs/Makefile create mode 100644 docs/footer.md create mode 100644 docs/monokai.css create mode 100644 docs/mplayer.md create mode 100644 docs/spman.md create mode 100644 docs/water.css (limited to 'docs') diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..83bb24b --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,18 @@ +all: msx-lib-ref.html spman-lib-ref.html mplayer-lib-ref.html + +msx-lib-ref.html: ../include/ubox.h ../tools/hdoc.py footer.md header.html + ../tools/hdoc.py --footer footer.md "ubox.lib reference" < ../include/ubox.h > reference.ubox.md + pandoc -s -t html5 -c water.css -c monokai.css --toc --no-highlight -F ../tools/pandocfilter-pygments.py -B header.html reference.ubox.md -o ubox-lib-ref.html + +spman-lib-ref.html: ../include/spman.h ../tools/hdoc.py footer.md spman.md header.html + ../tools/hdoc.py --header spman.md --footer footer.md "spman.lib reference" < ../include/spman.h > reference.spman.md + pandoc -s -t html5 -c water.css -c monokai.css --toc --no-highlight -F ../tools/pandocfilter-pygments.py -B header.html reference.spman.md -o spman-lib-ref.html + +mplayer-lib-ref.html: ../include/mplayer.h ../tools/hdoc.py footer.md mplayer.md header.html + ../tools/hdoc.py --header mplayer.md --footer footer.md "mplayer.lib reference" < ../include/mplayer.h > reference.mplayer.md + pandoc -s -t html5 -c water.css -c monokai.css --toc --no-highlight -F ../tools/pandocfilter-pygments.py -B header.html reference.mplayer.md -o mplayer-lib-ref.html + +clean: + rm -f ubox-lib-ref.html spman-lib-ref.html mplayer-lib-ref.html reference.ubox.md reference.spman.md reference.mplayer.md + +.PHONY: clean all diff --git a/docs/footer.md b/docs/footer.md new file mode 100644 index 0000000..276828c --- /dev/null +++ b/docs/footer.md @@ -0,0 +1,3 @@ +----- +**Copyright © 2020 Juan J. Martinez (jjm at usebox.net)** +Licensed [CC BY NC SA 4.0](http://creativecommons.org/licenses/by-nc-sa/4.0/). diff --git a/docs/monokai.css b/docs/monokai.css new file mode 100644 index 0000000..18556b5 --- /dev/null +++ b/docs/monokai.css @@ -0,0 +1,73 @@ +.highlight .hll { background-color: #49483e } +.highlight { background: #272822; color: #f8f8f2 } +.highlight .c { color: #75715e } /* Comment */ +.highlight .err { color: #960050; background-color: #1e0010 } /* Error */ +.highlight .k { color: #66d9ef } /* Keyword */ +.highlight .l { color: #ae81ff } /* Literal */ +.highlight .n { color: #f8f8f2 } /* Name */ +.highlight .o { color: #f92672 } /* Operator */ +.highlight .p { color: #f8f8f2 } /* Punctuation */ +.highlight .ch { color: #75715e } /* Comment.Hashbang */ +.highlight .cm { color: #75715e } /* Comment.Multiline */ +.highlight .cp { color: #75715e } /* Comment.Preproc */ +.highlight .cpf { color: #75715e } /* Comment.PreprocFile */ +.highlight .c1 { color: #75715e } /* Comment.Single */ +.highlight .cs { color: #75715e } /* Comment.Special */ +.highlight .gd { color: #f92672 } /* Generic.Deleted */ +.highlight .ge { font-style: italic } /* Generic.Emph */ +.highlight .gi { color: #a6e22e } /* Generic.Inserted */ +.highlight .gs { font-weight: bold } /* Generic.Strong */ +.highlight .gu { color: #75715e } /* Generic.Subheading */ +.highlight .kc { color: #66d9ef } /* Keyword.Constant */ +.highlight .kd { color: #66d9ef } /* Keyword.Declaration */ +.highlight .kn { color: #f92672 } /* Keyword.Namespace */ +.highlight .kp { color: #66d9ef } /* Keyword.Pseudo */ +.highlight .kr { color: #66d9ef } /* Keyword.Reserved */ +.highlight .kt { color: #66d9ef } /* Keyword.Type */ +.highlight .ld { color: #e6db74 } /* Literal.Date */ +.highlight .m { color: #ae81ff } /* Literal.Number */ +.highlight .s { color: #e6db74 } /* Literal.String */ +.highlight .na { color: #a6e22e } /* Name.Attribute */ +.highlight .nb { color: #f8f8f2 } /* Name.Builtin */ +.highlight .nc { color: #a6e22e } /* Name.Class */ +.highlight .no { color: #66d9ef } /* Name.Constant */ +.highlight .nd { color: #a6e22e } /* Name.Decorator */ +.highlight .ni { color: #f8f8f2 } /* Name.Entity */ +.highlight .ne { color: #a6e22e } /* Name.Exception */ +.highlight .nf { color: #a6e22e } /* Name.Function */ +.highlight .nl { color: #f8f8f2 } /* Name.Label */ +.highlight .nn { color: #f8f8f2 } /* Name.Namespace */ +.highlight .nx { color: #a6e22e } /* Name.Other */ +.highlight .py { color: #f8f8f2 } /* Name.Property */ +.highlight .nt { color: #f92672 } /* Name.Tag */ +.highlight .nv { color: #f8f8f2 } /* Name.Variable */ +.highlight .ow { color: #f92672 } /* Operator.Word */ +.highlight .w { color: #f8f8f2 } /* Text.Whitespace */ +.highlight .mb { color: #ae81ff } /* Literal.Number.Bin */ +.highlight .mf { color: #ae81ff } /* Literal.Number.Float */ +.highlight .mh { color: #ae81ff } /* Literal.Number.Hex */ +.highlight .mi { color: #ae81ff } /* Literal.Number.Integer */ +.highlight .mo { color: #ae81ff } /* Literal.Number.Oct */ +.highlight .sa { color: #e6db74 } /* Literal.String.Affix */ +.highlight .sb { color: #e6db74 } /* Literal.String.Backtick */ +.highlight .sc { color: #e6db74 } /* Literal.String.Char */ +.highlight .dl { color: #e6db74 } /* Literal.String.Delimiter */ +.highlight .sd { color: #e6db74 } /* Literal.String.Doc */ +.highlight .s2 { color: #e6db74 } /* Literal.String.Double */ +.highlight .se { color: #ae81ff } /* Literal.String.Escape */ +.highlight .sh { color: #e6db74 } /* Literal.String.Heredoc */ +.highlight .si { color: #e6db74 } /* Literal.String.Interpol */ +.highlight .sx { color: #e6db74 } /* Literal.String.Other */ +.highlight .sr { color: #e6db74 } /* Literal.String.Regex */ +.highlight .s1 { color: #e6db74 } /* Literal.String.Single */ +.highlight .ss { color: #e6db74 } /* Literal.String.Symbol */ +.highlight .bp { color: #f8f8f2 } /* Name.Builtin.Pseudo */ +.highlight .fm { color: #a6e22e } /* Name.Function.Magic */ +.highlight .vc { color: #f8f8f2 } /* Name.Variable.Class */ +.highlight .vg { color: #f8f8f2 } /* Name.Variable.Global */ +.highlight .vi { color: #f8f8f2 } /* Name.Variable.Instance */ +.highlight .vm { color: #f8f8f2 } /* Name.Variable.Magic */ +.highlight .il { color: #ae81ff } /* Literal.Number.Integer.Long */ + +div.highlight{padding-left:16px;display:block;overflow-x:auto;border-radius:6px} +nav>a{display:inline-block;margin-right: 1em} diff --git a/docs/mplayer.md b/docs/mplayer.md new file mode 100644 index 0000000..10e4689 --- /dev/null +++ b/docs/mplayer.md @@ -0,0 +1,83 @@ +## Overview + +**mplayer** provides easy access to Arkos 2 Minimal Player (AKM) ROM version +from SDCC. + +The library adds support for priority based sound effects, so it is possible +to have two uninterrupted channels for music and leave the third one for +effects. + +When the priority effects are used, an effect is played if no effect is +already being played or if the effect being played has less priority. The +effect number is used as priority, being effect number 1 the one with lowest +priority. + +The player comes with a generic configuration supporting all the features. If +the songs/effects don't use everything that AKM can offer, it is possible to +configure the player to remove features saving space and CPU. + +Arkos 2 Player is licensed MIT, please check `src/mplayer/akm/` directory for +further info about configuring the player. + +Visit [Arkos Tracker website](http://www.julien-nevo.com/arkostracker/) to +download the tracker. + +## Exporting songs and effects + +The player is quite complex and has a lot of options that can be disabled if +not used, reducing space and CPU use. + +**mplayer** is only a fixed interface, and the player is compiled customised to +the song and effects used by the game. + +Currently AKM can only be compiled with **rasm** (included in `./tools`), and then +processed with `Disark` to generate ASM compatible with `SDCC`. Once that code is +compiled, it will be relocated by the linker. + +Notes on **Disark**: + + - It is not open source yet, so it needs to be put in the PATH. It is + distributed as part of Arkos 2 Traker tools. + - Because it uses uppercase labels, the variable exported and accessible from + C will be all uppercase. For exampler: for `song` we will use `SONG`. + +This is automated, and the only counter-intuitive step is making an ASM file +for **rasm** such as: + +``` +; +; to build the custom AKM player with song + effects +; + +include "song_playerconfig.asm" +include "effects_playerconfig.asm" + +include "../../src/mplayer/akm/akm_ubox.asm" + +songDisarkGenerateExternalLabel: +include "song.asm" + +effectsDisarkGenerateExternalLabel: +include "effects.asm" +``` + +See the example game and the commands run automatically for further details. + +### Exporting the song + +In Arkos 2 Tracker, export the song as "AKM", using "Export as source file" and +"Generate configuration file for players". + +Save the file as `song.asm`. + +It should create `song_playerconfig.asm` in the same directory. + +### Exporting the effects + +In Arkos 2 Tracker, export the effects as "AKX", using "Export as source file" and +"Generate configuration file for players". + +Save the file as `effects.asm`. + +It should create `effects_playerconfig.asm` in the same directory. + diff --git a/docs/spman.md b/docs/spman.md new file mode 100644 index 0000000..b9512b8 --- /dev/null +++ b/docs/spman.md @@ -0,0 +1,36 @@ +## Overview + +**spman** is a simple sprite manager that provides: + +- support for 16x16 sprites. +- an easy way to manage sprite patterns. +- a simple yet effective sprite flicker that allows displaying more than 4 sprites + on the same line, with support for "fixed" sprites that are excluded from + flickering. + +It should be easy to modify and customize (`spman.c` is around 100 lines of code). + +The manager is used as follows: + +1. Initialize the manager with [spman_init](#spman_init). +2. Allocate patterns with [spman_alloc](#spman_alloc). This can be done at any + time, is not needed to allocate all the patterns in one go. +3. In the game loop: + - Allocate sprites to be drawn on screen, using + [spman_alloc_fixed_sprite](#spman_alloc_fixed_sprite) for sprites excluded + from the flicker and [spman_alloc_sprite](#spman_alloc_sprite) for any + other sprite. + - Update the sprites on screen with [spman_update](#spman_update). + +The allocate/update cycle needs to happen per frame, so the flicker function is +effective. The longer between updates, the slower the flickering will be. If +the game updates at least 25/30 FPS, that's good enough for most games. + +There are other functions to flush allocated sprites without updating the +screen, or to hide all the sprites on screen. + +The manager supports all 64 patterns and up to 31 visible sprites (one sprite +is used by the flicker). + +**spman** comes from "Sprite Pattern MANager". + diff --git a/docs/water.css b/docs/water.css new file mode 100644 index 0000000..c007230 --- /dev/null +++ b/docs/water.css @@ -0,0 +1,2 @@ +body{font-family:system-ui,-apple-system,BlinkMacSystemFont,Segoe UI,Roboto,Oxygen,Ubuntu,Cantarell,Fira Sans,Droid Sans,Helvetica Neue,sans-serif;line-height:1.4;max-width:800px;margin:20px auto;padding:0 10px;color:#dbdbdb;background:#202b38;text-rendering:optimizeLegibility}button,input,textarea{transition:background-color .1s linear,border-color .1s linear,color .1s linear,box-shadow .1s linear,transform .1s ease}h1{font-size:2.2em;margin-top:0}h1,h2,h3,h4,h5,h6{margin-bottom:12px}h1,h2,h3,h4,h5,h6,strong{color:#fff}b,h1,h2,h3,h4,h5,h6,strong,th{font-weight:600}button,input[type=button],input[type=checkbox],input[type=submit]{cursor:pointer}input:not([type=checkbox]),select{display:block}button,input,select,textarea{color:#fff;background-color:#161f27;font-family:inherit;font-size:inherit;margin-right:6px;margin-bottom:6px;padding:10px;border:none;border-radius:6px;outline:none}button,input:not([type=checkbox]),select,textarea{-webkit-appearance:none}textarea{margin-right:0;width:100%;box-sizing:border-box;resize:vertical}button,input[type=button],input[type=submit]{padding-right:30px;padding-left:30px}button:hover,input[type=button]:hover,input[type=submit]:hover{background:#324759}button:focus,input:focus,select:focus,textarea:focus{box-shadow:0 0 0 2px rgba(0,150,191,.67)}button:active,input[type=button]:active,input[type=checkbox]:active,input[type=submit]:active{transform:translateY(2px)}input:disabled{cursor:not-allowed;opacity:.5}::-webkit-input-placeholder{color:#a9a9a9}:-ms-input-placeholder{color:#a9a9a9}::-ms-input-placeholder{color:#a9a9a9}::placeholder{color:#a9a9a9}a{text-decoration:none;color:#41adff}a:hover{text-decoration:underline}code,kbd{background:#161f27;color:#ffbe85;padding:5px;border-radius:6px}pre>code{padding:10px;display:block;overflow-x:auto}img{max-width:100%}hr{border:none;border-top:1px solid #dbdbdb}table{border-collapse:collapse;margin-bottom:10px;width:100%}td,th{padding:6px;text-align:left}th{border-bottom:1px solid #dbdbdb}tbody tr:nth-child(2n){background-color:#161f27}::-webkit-scrollbar{height:10px;width:10px}::-webkit-scrollbar-track{background:#161f27;border-radius:6px}::-webkit-scrollbar-thumb{background:#324759;border-radius:6px}::-webkit-scrollbar-thumb:hover{background:#415c73} +/*# sourceMappingURL=dark.css.map */ -- cgit v1.2.3