The GFX9000 library provides a basic sets of routines that are very useful for people who'd like to develop their own GFX9000 programs. Alongside with the GFX9k library, there's a new graphics format: G9B. On this page, you can find the specifications.
The current version of the library is version 0.70. To use it, the GFX9k Lib must be assembled with sjasm. However, you can also use it with another assembler or C compiler by means of an export file.
The following functions are available in the current version of the library:
----------------------------------------------------------------------------; ; General Functions overview ; ;---------------------------------------------------------------------------; G9k.Reset ; Reset and initialize the Gfx9000 G9k.SetScreenMode ; Set screen mode G9k.SetVramWrite ; Set vram write address G9k.SetVramRead ; Set vram read address G9k.Detect ; Detect presence of the Gfx9000 G9k.DisplayEnable ; Enable display G9k.DisplayDisable ; Disable display G9k.SpritesEnable ; Enable sprites/mouse cursor G9k.SpritesDisable ; Disable sprites/mouse cursor G9k.WritePalette ; Write palette data to the Gfx9000 G9k.ReadPalette ; Read palette data from the Gfx9000 G9k.SetAdjust ; Adjust Gfx9000 display G9k.SetBackDropColor; Set backdrop color G9k.SetScrollX ; Set scroll X Layer A G9k.SetScrollY ; Set scroll Y Layer A G9k.SetScrollXB ; Set scroll X Layer B G9k.SetScrollYB ; Set scroll Y Layer B G9k.SetScrollMode ; Set scroll mode G9k.Close ; Closes a G9B or VFF file ;----------------------------------------------------------------------------; ; Blitter Function overview ; ;----------------------------------------------------------------------------; G9k.DrawFilledBox ; Draw filled box G9k.DrawBox ; Draw box G9k.DrawLine ; Draw line (simple) G9k.SetupCopyRamToXY ; Setup parameters for Ram to XY copy G9k.CopyRamToXY ; Copy data from Ram to XY G9k.SetupCopyXYToRam ; Setup parameters for XY to Ram copy G9k.CopyXYToRam ; Copy data from XY to Ram G9k.CopyXYToXY ; Copy XY to XY G9k.CopyXYToRegisterXY; Copy XY(struct) to XY (registers) G9k.CopyVramToXY ; Copy Linear vram address to XY G9k.CopyXYToVram ; Copy XY to Linear vram address G9k.SetCmdWriteMask ; Set blitter command write mask G9k.SetCmdColor ; Set blitter command color G9k.SetCmdBackColor ; Set command back ground color G9k.CopyRamToVram ; Copy data from ram to Linear vram address ;----------------------------------------------------------------------------; ; Font Function overview ; ;----------------------------------------------------------------------------; G9k.OpenVff ; Open a VFF file G9k.LoadFont ; Loads a VFF(V9990 font format) file from disk G9k.SetFont ; Set a font as default G9k.PrintString ; Print a zero terminated string G9k.PutChar ; Prints a character G9k.Locate ; Set X and Y coordinates for putchar ;----------------------------------------------------------------------------; ; Gfx9000 bitmap functions ; ;----------------------------------------------------------------------------; G9k.OpenG9B ; Open a G9B file G9k.ReadG9B ; Read data from disk to Gfx9000 VRAM X,Y G9k.ReadG9BLinear ; Read data from disk to Gfx9000 Linear VRAM Address ;----------------------------------------------------------------------------; ; Gfx9000 pattern functions ; ;----------------------------------------------------------------------------; G9k.SetPatternData ; Set pattern data G9k.PatternData ; Get partern data G9k.SetPattern ; Set pattern G9k.GetPattern ; Get pattern ;----------------------------------------------------------------------------; ; Macro overview ; ;----------------------------------------------------------------------------; ; G9kCmdWait - Wait for Blitter command completion ; G9kWriteReg - Write Gfx9000 register ; G9kReadReg - Read Gfx9000 register ; G9kWaitVsync - Wait for Vertical Sync
Alongside with the GFX9k Lib, there's a new graphics format: G9B. The G9B format is one of the key features of the G9KLIB. It is a flexible bitmap format which can be used in all GFX9000 modes, including pattern modes. In theory there is no limit to the dimensions of a GFX9000 bitmap. The size limit depends on the image space of the GFX9000. Unwanted results can occur when the bitmap is bigger than the image space.
All color modes are supported by G9B, except 1bit bitmaps. The GFX9000 doesn't have a 1 bit mode but it can use 1 bit images for characters and cursor sprites. A later version of the G9B format may support this mode.
A G9B file consist of the following fields:
[HEADER] g9bID DB "G9B" ; g9b identifier string headerSize DW 11 ; Length of the G9B_HEADER part. Length can change in updated versions. [G9B_HEADER] bitDepth DB 8 ; 2,4,8 or 16 bit colorType DB 0 ; 0=64 color palette mode, ; 64=256 color fixed, ; 128=YJK, ; 192=YUV mode nrColors DB 64 ; Number of colors in palette mode width DW 512 ; Width height DW 424 ; Height compression DB 1 ; 0 = no compression, ; 1 = bitbuster compression, ; other value = future expansions dataSize DS 3 ; 24 bit data size [PALETTE_DATA] palette DS nrColors*3 ; If the number of colors is zero then this field does not exist [BITMAP_DATA] data DS dataSize ; The bitmap data, this can either be raw data or bitbuster data
NOTE: Values used are example values.
In the software G9B files are referred to as objects. The following functions are available for G9B files:
These functions use the object G9B_OBJECT. The definition of this object can be found in the g9klib.inc file:
STRUCT G9B_OBJECT fileHandle WORD ; Dos2 file handle from the openend G9B file bitDepth BYTE ; 2,4,8 or 16 bit colorType BYTE ; 0=64 color palette mode,64=256 color fixed, ; 128=YJK and 192=YUV mode nrColors BYTE ; Number of colors in palette mode width WORD ; Width height WORD ; Height compression BYTE ; 0 = no compression, other value = compression used dataSize D24 ; 24 bit data size ENDS
When you want to define a G9B_OBJECT object, but you don't want to use SJASM, then simply define an area of 13 bytes.
A G9B file must be opend with G9k.OpenG9B. This function opens the file (by default with the DOS2 function _OPEN), and the header is read. An error is returned when it's not a valid G9B file. After opening, all the fields of the G9B_OBJECT can be checked by the user.Then, the user can decide to read the rest of the file by calling G9k.ReadG9B or G9k.ReadG9BLinear.
Note: G9k.OpenG9B doesn't check if the G9B file is compatible with the current selected GFX9000 screen mode.
For examples, check out the source file of G9BView.com or g9ktest.com. Both are included in the G9kLIB package.
Function : G9k.OpenG9B
Description : Opens a G9B file
Input : DE = Pointer to zero terminated file name
: HL = Pointer to an unused/empty G9B_OBJECT
Output : G9B_OBJECT filled in with G9B header
Return value : A = ERROR CODE
: - _NOG9B = File is not A G9B File
: - DOS2 error Code. In this case Bdos.ERROR_STRING is filled with
: the DOS2 error explaination string.
Modifies : AF,BC,DE,HL
Function : G9k.ReadG9B
Description : Reads a G9B file and copies the data to the GFX9000 vram to location X,Y
Input : IX = Pointer to G9B_OBJECT
: DE = Pointer to load buffer
: BC = Size of load buffer, size of buffer is not used with bitbust compressed files,
; however, always specify a biffer size, so compressed and uncompressed
; files can be loaded with the same parameters
: HL = Destination X in vram
: IY = Destination Y in vram
: A = Palette pointer. Only valid with in palette modes. The value of the
; palette pointer can be calculated with startColorNumber * 4
Return value : A = ERROR CODE
: - DOS2 error Code. In this case Bdos.ERROR_STRING is filled with
: the DOS2 error explaination string.
Modifies : AF,BC,DE,HL
Function : G9k.ReadG9Blinear
Description : Reads a G9B file and copies the data linear to the GFX9000 vram
Input : IX = Pointer to G9B_OBJECT
: DE = Pointer to load buffer
: BC = Size of load buffer, size of buffer is not used with bitbust compressed
; files, however, always specify a buffer size, so compressed
; and uncompressed files can be loaded with the same parameters
: IYL:HL = Vram destination address
: A = Palette pointer. Only valid with in palette modes. The value of the palette
: pointer can be calculated with: startColorNumber * 4;
Return value : A = ERROR CODE
: - DOS2 error Code. In this case Bdos.ERROR_STRING is filled with
: the DOS2 error explaination string.
Modifies : AF,BC,DE,HL
Function : G9k.Close
Description : Closes the file handle of an object. This the generic close function for objects
: used within the GFX9000 library
Input : IX = Pointer to G9B_OBJECT
Output : G9B_OBJECT = file handle is closed
Return value : A = ERROR CODE
: - DOS2 error Code. In this case Bdos.ERROR_STRING is filled with
: the DOS2 error explaination string.
Modifies : AF,BC,DE,HL
The following G9B output modes are supported:
| Input format | Output format |
|---|---|
| TIM 15 bit | 15 bit G9B |
| BMP 1 bit | 2 bit G9B |
| BMP 4 bit | 4 bit G9B |
| BMP 8 bit | 8 bit 64 color G9B |
| BMP 24bit | 8 bit YJK G9B |
| BMP 24bit | 8 bit YUV G9B |
| BMP 24bit | 15 bit |
There are some known limitations to V9BMP. These are:
The following output formats are supported:
| Input format | Output format |
|---|---|
| BMP 1 bit | 2 bit G9B |
| BMP 4 bit | 4 bit G9B |
| BMP 8 bit | 8 bit 64 color G9B |
| BMP 24bit | 8 bit fixed colors G9B |
| BMP 24bit | 8 bit YJK G9B |
| BMP 24bit | 8 bit YUV G9B |
| BMP 24bit | 15 bit |
BMP2G9B can also be used to generate patterns for bitmap modes. This means that the patterns are stored in the VRAM in a linear way. They must be loaded with G9k.ReadG9BLinear. A linear copy to XY can now be used with these patterns. The linear copy to XY is faster than the XY to XY copy. This is why the pattern mode option is created for bitmap modes. Optional dithering can be applied. In some cases this will result in a better looking end result.
G9bview is a viewer for g9b files. G9Bview is built using routines from the G9KLIB and is provided in the G9kLIB package to view and test created G9B files on the GFX9000. ViewMSX can be used to view G9B files on Windows.
G9bview is command line based and accepts wild cards as parameters. For example:
g9bview *.g9b
During viewing the following keys can be used:
The g9klib package contains 2 MSX tools and 1 PC tool. You can use V9BMP and G9Bview for the MSX and BMP2G9B for the PC (MS-WINDOWS). G9B files can be created with V9BMP and BMP2G9B. V9MP doesn't support compression. BMP2G9B can also be used to compress non-compressed G9B files.
The zip file contains the sources and a few example programs.