Initial import1.0

6 files changed, 215 insertions, 0 deletions

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 &copy; 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 */