diff --git a/f256lib.adoc b/f256lib.adoc index 155a67c..036027e 100644 --- a/f256lib.adoc +++ b/f256lib.adoc @@ -27,6 +27,9 @@ within a C program. In addition, *_F256lib_* also unleashes the power of the F256 by automatically handling most of the sometimes tricky memory management and paging required to truly harness the power of the system. +TIP: Although fairly complete, not every feature of the Foenix F256 computers are +supported yet. Not finding a feature you need? <>! + == Audience @@ -34,6 +37,9 @@ the sometimes tricky memory management and paging required to truly harness the This document is not an introduction to programming. It assumes you are comfortable with your host OS and working from the command line. +Example pathnames in this document are usually in Windows format. +Linux and MacOS folks, you can cope. + == Requirements @@ -95,7 +101,8 @@ your F256. See: https://github.com/pweingar/FoenixMgr Just re-run your `f256-install` script! -WARNING: This will *delete* the `f256dev` folder! +WARNING: This will *delete* the `f256dev` folder! Do *NOT* put your own data +in this folder! @@ -111,19 +118,24 @@ crazy. While we've tried to simplify things, do not be afraid to dig into the source code for *_F256lib_* and the included tools! - [quote,Some Code Monkey Jedi] Use the Source, Luke! +This manual also assumes you have familiariazed yourself with the +https://github.com/pweingar/F256Manual[hardware documentation] +for the Foenix F256. Without knowing the capabilities of the machine, +it's going to be hard to program in any lanugage with any toolkit! + == Amalgamated or Not? -*_F256lib_* is distributed in two formats. _Amalgamated_ (everything in a single header file) or as individual source files for each -section of the API. +*_F256lib_* is distributed in two formats. _Amalgamated_ (everything in a +single header file) or as individual source files for each section of the API. -We *highly* recommend using the amalgamated build unless you are interested in working on the library -itself. The included build tools do not support using the non-amalgamated version out-of-the-box. +We *highly* recommend using the amalgamated build unless you are interested +in working on the library itself. The included build tools do not support +using the non-amalgamated version out-of-the-box. @@ -183,8 +195,11 @@ UNIX folks, flip your slashes! ---- -When using `f256build` to build your projects, the include path will be set automatically. +NOTE: When using `f256build` to build your projects, the include path will be set automatically. +After a successful build, an overview of memory usage will be displayed. Double-check +this to ensure it appears "sane" for your program! If you run out of space in +either near memory or an overlay bank, you'll see errors here. === Running Your Project @@ -211,10 +226,20 @@ useful information can be found in the `.builddir` directory that is created under your program's project directory. + == Definitions -* `low memory`: the first 64k of memory (0x0000 to 0xffff). +* `block`: an 8k segment of memory, aligned on 8k boundaries. * `far memory`: RAM not directly accessable by the CPU (from 0x10000 on). +* `low memory`: the first 64k of memory (0x0000 to 0xffff). +* `overlay`: code that lives in far memory that is automatically paged in on demand. +* `slot`: an 8k segment of near memory, aligned on 8k boundaries, where blocks can be paged in. +* `word`: on the F256, a word is 16 bits. + +TIP: Be sure to check the F256 hardware documentation to ensure the memory +range you wish to use is valid for what you are trying to accomplish. +For example, not all `far memory` addresses can be accessed by the video +subsystem. Know your hardware! @@ -267,6 +292,9 @@ The *_F256lib_* API is broken down into several general sections: | Bare minimum features needed to support the compiler standard library. |=== +NOTE: Several sections of the documentation mention "screen refresh rate" +dependent settings. At this time, *_F256lib_* only supports 60 Hz. + == API Details @@ -686,98 +714,381 @@ clock, if available. === Text +On startup, the text layer is cleared, background colors are disabled, the +foreground color is set to white, the background to black, the cursor disabled, +and the font set to double-height producing an 80 column by 25 line display. + [,c] ---- void textClear(void); ---- +Clears the text layer to the current text colors. Returns the cursor to the +upper-left corner. + [,c] ---- void textDefineBackgroundColor(byte slot, byte r, byte g, byte b); ---- +Defines one of the 16 available colors in the text background color table. +`slot` specifies which color to define, 0 through 15. `r`, `g`, and `b` specify +how much of each color component to use, 0 through 255. + [,c] ---- void textDefineForegroundColor(byte slot, byte r, byte g, byte b); ---- +Defines one of the 16 available colors in the text foreground color table. +`slot` specifies which color to define, 0 through 15. `r`, `g`, and `b` specify +how much of each color component to use, 0 through 255. + [,c] ---- void textEnableBackgroundColors(bool b); ---- +Enabling background colors obscures any graphics layers behind the text layer. + [,c] ---- void textGetXY(byte *x, byte *y); ---- +Returns the position of the cursor in the pointers `x` and `y`. + [,c] ---- void textGotoXY(byte x, byte y); ---- +Moves the cursor to a new position at `x`, `y`. The valid values for the new +location depend on the current screen refresh rate and text doubling settings. + [,c] ---- void textPrint(char *message); ---- +Displays the string `message` at the current cursor position. This function +uses much less code than using `printf()`. + [,c] ---- void textPrintInt(int32_t value); ---- +Displays the signed integer `value` at the current cursor position. This function +uses much less code than using `printf()`. + [,c] ---- void textPrintUInt(uint32_t value); ---- +Displays the unsigned integer `value` at the current cursor position. This function +uses much less code than using `printf()`. + [,c] ---- void textSetColor(byte f, byte b); ---- +Specifies which color slots to use for the foreground and background colors of +future text output. + [,c] ---- void textSetCursor(byte c); ---- +Specifies which ASCII character code to use as a cursor. Setting the cursor +to `0` will disable it. + [,c] ---- void textSetDouble(bool x, bool y); ---- +Specifies wether or not to double the size of displayed characters on the `x`, +`y`, or both axis. Depending on the video refresh rate, this allows you to +produce text displays of the following sizes: + +* At 60 Hz: +** 80x60 +** 40x60 +** 80x30 +** 40x30 + +* At 70 Hz: +** 80x50 +** 40x50 +** 80x25 +** 40x25 + + === Graphics +Functions in this category affect the graphics system in general. They are used +to configure layers, colors, etc. To actually produce something on the display, +you'll need to use these functions in conjunction with functions from another +graphics subsystem. + +The graphics system consists of three layers. By default, each layer is set +to its associated `bitmap`. (Layer 0 is Bitmap 0 and so on.) + +==== graphicsDefineColor + +[,c] +---- void graphicsDefineColor(byte clut, byte slot, byte r, byte g, byte b); +---- + +Defines one of the 256 available colors in one of the four graphics color tables. +`clut` is which color lookup table to modify, 0 through 4. `slot` specifies +which color index to define, 0 through 255. `r`, `g`, and `b` specify +how much of each color component to use, 0 through 255. + +==== graphicsSetLayerBitmap + +[,c] +---- void graphicsSetLayerBitmap(byte layer, byte which); +---- + +Specifies that `layer` (0 to 3) should display bitmap number `which` (0 to 3). + +==== graphicsSetLayerTile + +[,c] +---- void graphicsSetLayerTile(byte layer, byte which); +---- + +Specifies that `layer` (0 to 3) should display tilemap number `which` (0 to 3). + +==== graphicsWaitVerticalBlank + +[,c] +---- void graphicsWaitVerticalBlank(void); +---- + +Pauses program execution until the start of a vertical blank. + + === Bitmaps +The Foenix F256 can display up to three full-screen bitmaps at a time. Depending +on the screen refresh, the bitmaps are: + +* At 60 Hz: +** 320x240 pixels + +* At 70 Hz: +** 320x200 pixels + +On startup, all three bitmaps are assigned to each associated graphics layer, +but are not visible. The three bitmaps are located at the following memory +addresses: + +* Page 0 - 0x6c000 -> 0x7ebff +* Page 1 - 0x58000 -> 0x6abff +* Page 2 - 0x44000 -> 0x56bff + +IMPORTANT: Be sure your program avoids using these memory ranges if you use +these pages! + +NOTE: You may have noticed each bitmap page is aligned on an 8k boundary leaving +5k unused between each page. If you need this memory, go for it. + +==== bitmapClear + +[,c] +---- void bitmapClear(void); +---- + +Clears the currently active bitmap to the current color. + +==== bitmapGetResolution + +[,c] +---- void bitmapGetResolution(uint16_t *x, uint16_t *y); +---- + +Returns the size of the current bitmap in the pointers `x` and `y`. + +==== bitmapLine + +[,c] +---- void bitmapLine(uint16_t x1, uint16_t y1, uint16_t x2, uint16_t y2); +---- + +Draws a line on the current bitmap in the current color from +`(x1, y1)` to `(x2, y2)`. + +==== bitmapPutPixel + +[,c] +---- void bitmapPutPixel(uint16_t x, uint16_t y); +---- + +Plots a single pixel on the current bitmap in the current color at +`(x, y)`. + +==== bitmapSetActive + +[,c] +---- void bitmapSetActive(byte p); +---- + +Specifies the currently active bitmap from 0 to 3. + +==== bitmapSetAddress + +[,c] +---- void bitmapSetAddress(byte p, uint32_t a); +---- + +Allows you to change where in far memory a bitmap is located. Bitmap page `p` +will be assigned to start at memory address `a`. Addresses must be aligned on +an 8k boundary (evenly divisible by 8192). + +==== bitmapSetCLUT + +[,c] +---- void bitmapSetCLUT(byte clut); +---- + +Specifies which color look up table to use for the current bitmap. Each bitmap +can have its own palette of 256 colors. + +==== bitmapSetColor + +[,c] +---- void bitmapSetColor(byte c); +---- + +Specifies the current color index in the current color table to use for future +drawing operations on the current bitmap. + +==== bitmapSetVisible + +[,c] +---- void bitmapSetVisible(byte p, bool v); +---- + +Specifies if bitmap page `p` is visible or not. + + === Sprites +The Foenix F256 provides 64 independent sprites with three sprite layers. +Sprites are small bitmaps of the following sizes: + +* 8x8 +* 16x16 +* 24x24 +* 32x32 + +To allow sprites to smootly enter and exit the screen, sprite coordinates are +larger than bitmap and tile coordinates. Sprite coordinates are: + +* For 60 Hz: +** 352x272 + +* For 70 Hz: +** 352x232 + +The first 32 pixels are off the screen to the left and top. Sprites beyond the +horizontal and vertical resolutions shown are off the right and bottom of the +screen. See the hardware documentation for more details. + +==== spriteDefine + +[,c] +---- void spriteDefine(byte s, uint32_t address, byte size, byte CLUT, byte layer); +---- + +Assigns a block of memory to a given sprite. Sprite number `s` (0 to 63) will +pull its pixel data starting at `address` which can be in either near or far +memory. `size` is either 8, 16, 24, or 32. Each sprite can pull its color +information from one of the four (0 to 3) color lookup tables specified in +`CLUT`. `layer` specifies which of the three sprite layers you wish to use +(0 to 2). + +==== spriteSetPosition + +[,c] +---- void spriteSetPosition(byte s, uint16_t x, uint16_t y); +---- + +Positions sprite number `s` at location `(x, y)`. + +TIP: Remember! Sprite coordinates are not the same as other graphics coordinates! + +==== spriteSetVisible + +[,c] +---- void spriteSetVisible(byte s, bool v); +---- + +Determines if sprite number `s` is visible on the display. All sprites begin +life hidden. + + === Tiles +Tile maps are composed of individual "tiles" of pixels that are either 8x8 or +16x16 in size. Tile maps can be smoothly scrolled horizontally and vertically. +Like bitmaps and sprites, each + +==== tileDefineTileMap + +[,c] +---- void tileDefineTileMap(byte t, uint32_t address, byte tileSize, uint16_t mapSizeX, uint16_t mapSizeY); +---- + +==== tileDefineTileSet + +[,c] +---- void tileDefineTileSet(byte t, uint32_t address, bool square); +---- + +==== tileSetScroll + +[,c] +---- void tileSetScroll(byte t, byte xPixels, uint16_t xTiles, byte yPixels, uint16_t yTiles); +---- + +==== tileSetVisible + +[,c] +---- void tileSetVisible(byte t, bool v); +---- + + === File I/O