logo

GFX9000 libray

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.

Available functions

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

G9B graphics format

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.

File format

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.

Using G9B files

In the software G9B files are referred to as objects. The following functions are available for G9B files:

The G9B_OBJECT

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.

Opening files

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 overview

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     

Creating G9B files

G9B Files can be created on PC or on your (t)rusty MSX. On PC you can use BMP2G9B.exe and on MSX V9BMP. Both tools have a built-in help. Only a list of supported file types and output formats is listed here.

V9BMP.COM V1.1

Supported input formats for V9BMP are:

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:

BMP2G9B.EXE V0.7

Output files can be either in raw or in bitbuster compressed mode. Default is bitbuster compressed. The supported input formats for BMP2G9B 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.

G9B view

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.

System requirements

Viewing files

G9bview is command line based and accepts wild cards as parameters. For example:

g9bview *.g9b

During viewing the following keys can be used:

Downloads

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.