Public_Skunkworks/f256
Public_Skunkworks/f256
1
0
Fork 0
Code Issues 3 Pull requests Projects Releases Packages Wiki Activity Actions

Even more docs.

Browse source
This commit is contained in:
Scott Duensing 2024-06-06 01:54:11 -05:00
parent 455af00e64
commit 7981304429
1 changed files with 319 additions and 8 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

327
f256lib.adoc
View file

@ -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? <<Support,Let us know>>!
== 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