VDP TMS9918A MSX ROM SDCC Library (fR3eL Project)

Version: 1.2 (22/12/2020)
Author: mvac7 [mvac7303b@gmail.com]
Architecture: MSX
Format: C Object (SDCC .rel)
Programming language: C and Z80 assembler


History of versions:
 - v1.2 (22/12/2020) Conversion to source in C and added Sprite initialization 
                     functions.
 - v1.1 (14/02/2014) 
 - v1.0 (11/02/2014) 

 
>>> Warning!: Document pending correction. <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<


--------------------------------------------------------------------------------
Index:

1 Introduction
2 Acknowledgments.
3 Requirements
4 Constants
  4.1 Screen modes 1
  4.2 Screen modes 2
  4.3 Palette color codes
  4.4 VRAM address tables T1 (screen 0)
  4.5 VRAM address tables G1 (screen 1)
  4.6 VRAM address tables G2 (screen 2)
  4.7 VRAM address tables MC (screen 3)
5 Functions
  5.1 SCREEN
  5.2 SetSpritesSize
  5.3 SetSpritesZoom
  5.4 COLOR
  5.5 VPOKE
  5.6 VPEEK
  5.7 FillVRAM
  5.8 CopyToVRAM
  5.9 CopyFromVRAM
  5.10 SetVDP                       


--------------------------------------------------------------------------------
1 Introduction:

Open Source library with basic functions to work with the TMS9918A video 
processor.

It uses the functions from the MSX BIOS, so it is designed to create 
applications in ROM format.

Use them for developing MSX applications using Small Device C Compiler (SDCC) 
cross compiler.

In the source code (\examples), you can find applications for testing and 
learning purposes.

If you need specific functions to manage Sprites, you can use any of the 
following libraries:

- SPRITES Small (https://github.com/mvac7/SDCC_VDP_SPRITES_S_MSXROM_Lib) - 
  Basic functions for managing Sprites. It is more compact so it takes up less 
  space in our application.

- SPRITES (https://github.com/mvac7/SDCC_VDP_SPRITES_MSXROM_Lib) - 
  It includes the same functions as the Small version and adds to access 
  specific parameters (positioning, color, pattern, visibility and EarlyClock).

- SPRITES 1/2 (https://github.com/mvac7/SDCC_VDP_SPRITES_12_MSXROM_Lib) - 
  Same as SPRITES but in the G3 screen mode (V9938), it treats the color 
  parameters in a simplified way. Assign the color parameters and EarlyClock to 
  all the lines of the Sprites.

- SPRITES DUMP (In development) - Uses a buffer in RAM that has to be dumped in 
  each interruption. Includes a Sprite Flicker, to allow viewing up to 8 sprites 
  per line.


This library is part of the MSX fR3eL Project
      https://github.com/mvac7/SDCC_MSX_fR3eL

Enjoy it!
                           


--------------------------------------------------------------------------------
2 Acknowledgments
  
I want to give a special thanks to all those who freely share their knowledge 
with the MSX developer community.

* Avelino Herrera > http://msx.atlantes.org/index_es.html
* Nerlaska > http://albertodehoyonebot.blogspot.com.es
* Marq/Lieves!Tuore > http://www.kameli.net/marq/  http://www.kameli.net/lt/
* Fubukimaru https://github.com/Fubukimaru http://www.gamerachan.org/fubu/
* Andrear > http://andrear.altervista.org/home/msxsoftware.php
* Ramones > https://www.msxblog.es/tutoriales-de-programacion-en-ensamblador-ramones/
            MSXbanzai http://msxbanzai.tni.nl/dev/faq.html
* Sapphire/Z80ST > http://z80st.auic.es/
* Fernando García > https://www.youtube.com/user/bitvision
* Eric Boez > https://github.com/ericb59
* MSX Assembly Page > http://map.grauw.nl/resources/msxbios.php
* Portar MSX Tech Doc > https://problemkaputt.de/portar.htm
* MSX Resource Center > http://www.msx.org/
* Karoshi MSX Community (RIP 2007-2020)
* BlueMSX emulator > http://www.bluemsx.com/
* OpenMSX emulator > http://openmsx.sourceforge.net/
* Meisei emulator > ?



--------------------------------------------------------------------------------
3 Requirements:

  * Small Device C Compiler (SDCC) v3.9 
    http://sdcc.sourceforge.net/
  
  * Hex2bin v2.5 
    http://hex2bin.sourceforge.net/ 
   
   

--------------------------------------------------------------------------------
4 Constants


4.1 Screen modes 1

 Label   Value   Description
-------- ------- ---------------------------------------------------------------
 TXT40   0x00    text mode       (screen 0)
 TXT32   0x01    graphics 1 mode (screen 1)
 GRAPH1  0x02    graphics 2 mode (screen 2)
 GRAPH2  0x03    multicolor mode (screen 3)


4.2 Screen modes 2

 Label   Value   Description
-------- ------- ---------------------------------------------------------------
 T1      0x00    text mode       (screen 0)
 G1      0x01    graphics 1 mode (screen 1)
 G2      0x02    graphics 2 mode (screen 2)
 MC      0x03    multicolor mode (screen 3)


4.3 Palette color codes

 Label        Value 
------------- ------
 TRANSPARENT   0
 BLACK         1
 GREEN         2
 LIGHT_GREEN   3
 DARK_BLUE     4
 LIGHT_BLUE    5
 DARK_RED      6
 CYAN          7
 RED           8
 LIGHT_RED     9
 DARK_YELLOW  10
 LIGHT_YELLOW 11
 DARK_GREEN   12
 MAGENTA      13
 GRAY         14
 GREY         14
 WHITE        15


4.4 VRAM address tables T1 (screen 0)

 Label   Value   Description
-------- ------- ---------------------------------------------------------------
 BASE0   0x0000  name table
 BASE2   0x0800  character pattern table


4.5 VRAM address tables G1 (screen 1)

 Label   Value   Description
-------- ------- ---------------------------------------------------------------
 BASE5   0x1800  name table
 BASE6   0x2000  color table
 BASE7   0x0000  character pattern table
 BASE8   0x1B00  sprite attribute table OAM
 BASE9   0x3800  sprite pattern table


4.6 VRAM address tables G2 (screen 2)

 Label   Value   Description
-------- ------- ---------------------------------------------------------------
 BASE10  0x1800  name table
 BASE11  0x2000  color table
 BASE12  0x0000  character pattern table
 BASE13  0x1B00  sprite attribute table OAM
 BASE14  0x3800  sprite pattern table


4.7 VRAM address tables MC (screen 3)

 Label   Value   Description
-------- ------- ---------------------------------------------------------------
 BASE15  0x0800  name table
 BASE17  0x0000  character pattern table
 BASE18  0x1B00  sprite attribute table OAM
 BASE19  0x3800  sprite pattern table


4.8 G2 BANKs addends:

 Label   Value   Description
-------- ------- ---------------------------------------------------------------
 BANK0   0x0000
 BANK1   0x0800
 BANK2   0x1000





--------------------------------------------------------------------------------
5 Functions


================================================================================
5.1 SCREEN

 Function : 
            void SCREEN(char)
            
 Description:
            Sets the display mode of the screen.
            
 Input    : 
            [char] number of screen mode
                             
 Output   :
            - 
                            
 Examples : 
            SCREEN(2);
  
            SCREEN(GRAPH1);
            


================================================================================
5.2 SetSpritesSize

 Function : 
            void SetSpritesSize(char size)
            
 Description:
            Set size type for the sprites.
            
 Input    : 
            [char] size: 0=8x8; 1=16x16
                             
 Output   :
            - 
                            
 Examples :  
            SetSpritesSize(1);



================================================================================
5.3 SetSpritesZoom

 Function : 
            void SetSpritesZoom(boolean zoom)
            
 Description:
            Set zoom type for the sprites.
            
 Input    : 
            [boolean] zoom: false/0 = x1; true/1 = x2
                             
 Output   :
            - 
                            
 Examples : 
            SetSpritesZoom(true);



================================================================================
5.4 COLOR

 Function : 
            void COLOR(char, char, char)
            
 Description:
            Specifies the ink, foreground and background colors.
            
 Input    : 
            [char] ink color
            [char] background color
            [char] border color
                             
 Output   :
            -
                             
 Examples :
            COLOR(15, 4, 4);
              
            COLOR(WHITE, DARK_BLUE, BLACK);



================================================================================
5.5 VPOKE

 Function : 
            void VPOKE(unsigned int, char)
            
 Description:
            Writes a byte to the video RAM.
            
 Input    : 
            [unsigned int] VRAM address
            [char] value                 
 Output   :
            -
                             
 Examples :
            VPOKE(0x1000, 255);

            VPOKE(BASE10+100, 0x20);



================================================================================
5.6 VPEEK

 Function : 
            char VPEEK(unsigned int)
            
 Description:
            Reads data from the video RAM.
            
 Input    : 
            [unsigned int] VRAM address
                             
 Output   :
            [char] value
                             
 Examples :
            value = VPEEK(0x1000);
       
            value = VPEEK(BASE10+48);
 


================================================================================
5.7 FillVRAM

 Function : 
            void FillVRAM(unsigned int, unsigned int, char)
            
 Description:
            Fill a large area of the VRAM of the same byte.
            
 Input    : 
            [unsigned int] address of VRAM
            [unsigned int] blocklength
            [char] Value to fill.
                             
 Output   :
            -
                             
 Examples :
            FillVRAM(BASE10,768,0x00);
            
            FillVRAM(BASE11+BANK1,1024,32);
 


================================================================================
5.8 CopyToVRAM

 Function : 
            void CopyToVRAM(unsigned int, unsigned int, unsigned int)
            
 Description:
            Block transfer from memory to VRAM. 
            
 Input    : 
            [unsigned int] address of RAM
            [unsigned int] address of VRAM
            [unsigned int] blocklength
                             
 Output   :
            -
                             
 Examples :
            CopyToVRAM(0xE000,BASE12,1024);
 
 

================================================================================
5.9 CopyFromVRAM

 Function : 
            void CopyFromVRAM(unsigned int, unsigned int, unsigned int)
            
 Description:
            Block transfer from VRAM to memory.
            
 Input    : 
            [unsigned int] address of VRAM
            [unsigned int] address of RAM
            [unsigned int] blocklength
                             
 Output   :
            -
                             
 Examples :
            CopyFromVRAM(BASE12,0xE000, 1024);
 


================================================================================
5.10 SetVDP

 Function : 
            void SetVDP(char, char)
            
 Description:
            Writes a value in VDP registers.
            
 Input    : 
            [char] VDP register
            [char] value
                             
 Output   :
            -
                             
 Examples :
            SetVDP(1, 0b00000011);



--------------------------------------------------------------------------------

  
