********************************************************************************
GPU_GEO_tb.sv, for ModelSim and Active-HDL.
********************************************************************************

tests and simulate Nockieboy's 8 bit GPU geometry graphics drawing engine from:
https://github.com/nockieboy/gpu

******************************************************************************************************
Features control from a source ASCII text file script, and a 256 color .BMP picture file generator.
******************************************************************************************************

Tested on free Altera ModelSim 10 & 20.  Built in parameter (USE_ALTERA_IP) when disabled prevents the use of any Altera specific IP functions.

Written by Brian Guralnick.

v1.00 Sept 12, 2021

To setup simulation, Start Modelsim, then go to 'File - Change Directory' and select this files directory.  Then in the transcript, type:

- setup_ModelSim.do

(or if you want to enable the Altera megafunction IP, LPM_MULT & SCFIFO)

- do setup_altera.do

To change the 'TB_COMMAND_SCRIPT_FILE' source script file string and re-run the simulation, type:

- do test_8bitfont.do
- do test_45deg.do
- do test_art.do
- do test_blitter.do
- do test_blitter_hires.do
- do test_vwait.do

Note that some of these, like 'test_45deg.do', can take a minute to simulate.

********************************************************************************
For Active-HDL (Comes with older Lattice Diamond FPGA development environment.)
********************************************************************************

Go to 'File - New / Design'
- Create an empty design.
- Choose Verilog for HDL language, ignore 'Target Technology'.
- Type in 'GPU_GEO_tb' for design name.
- Next/Finish.
       
Unzip all the files directly into the 'src' directory inside the 'GPU_GEO_tb' folder. In the console, type:

- do setup_active-hdl.do

*** The result 'xxxx.bmp' and 'GEO_tb_command_results.txt' files generated by the simulation will be located in the main 'GPU_GEO_tb' folder.

Active-HDL does not support the changing of a string in a .sv file, so to run the different tb ASCII script demos, you need to copy the:

- GEO_tb_art.txt
- GEO_tb_Blitter.txt
- GEO_tb_Blitter_hires.txt
- GEO_tb_45deg_zilog.txt
- GEO_tb_8bit_font.txt
- GEO_tb_vwait.txt

over the 'GEO_tb_command_list.txt' file, then do a restart & run simulation.


*******************************************************************************
Run the following commands from a .txt source script file:
*******************************************************************************

- LOG_FILE  <FILE_NAME>            > Generates a results log file.         (No spaces allowed in file name).
                                   > The 'LOG_FILE  <FILE_NAME> ' will contain the command the Z80 CPU needed to send to the geometry unit to replicate the graphics results.

- END_LOG_FILE                     > Forcefully closes/ends the log file.
- STOP                             > Stops the script processing/simulation.  Click on 'run -all' to continue script after the stop command.
- END                              > Ends the script processing/simulation. (You may now paint/set your own manual controls in the waveform view and run -all)

- LOAD_GPU_RAM <file_name.bin>     > Reads a binary file, up to 1 megabyte, into the GEO pixel-writer memory.  
- SAVE_GPU_RAM <file_name.bin>     > Saves GEO pixel-writer 1 megabyte memory into a binary file.
- CLR_GPU_RAM                      > Clears the GPU memory

- CLR_BMP      <color_byte>        > Clears the test geometry_plotter bitmap memory to a set byte.  (This is not the pixel writer)

- SAVE_GEO_BMP   <FILE_NAME> <width> <height> <1=B&W>            > Saves a 256 color BMP picture of the geometry_plotter's output, NOT GPU Ram. Max 2048x2048.  <1=B&W> or 0 for dummy 256 color palette
- SAVE_PIXIE_BMP <FILE_NAME> <src/dest> <width> <height> <1=B&W> > Saves a 256 color BMP picture of the pixie-writer system GPU memory. SET_PAGET settings must be set & PIXIE must be enabled prior to draw commands.  <1=B&W> or 0 for dummy 256 color palette

- RESET                            > Sends a reset to the geometry unit.
- ENA_PIXIE <0/1>                  > Enables/disables pixel writer.  (Pixel writer is disabled by default)
- WAIT_IDLE <0/1>                  > Waits for the all processes to finish whatever they are currently doing before running next command. IE 1 command at a time.

- SEND_CMD <h0000-hFFFF>           > send a raw command, 16 bit hex value

- SET_XY  <x/y> <0..3> <decimal>                             > Sets 12 bit register X or Y with 12 bit decimal value 0-4095, basically calls SEND_CMD with the right value.
- SET_PAGET <src/dest> <base_address_hex> <width> <depth>    > Sets PAGET's (pixel address generator) source/dest   memory address, image width, color depth in bits/pixel = (1/2/4/8/16).
- SET_MAX_XY <x>   <y>                                       > Sets the maximum destination XY resolution.

- DRAW PIXEL <X>   <Y>   <c>                                          > Draws a dot at coordinates [XY], c=color(0..255)
- DRAW LINE  <aX>  <aY>  <bX>  <bY>  <c>                              > Draws a line from coordinates a[XY] to b[XY].
- DRAW BOX   <aX>  <aY>  <bX>  <bY>  <c>   <f>                        > Draws a box from top left a[XY] to bottom right b[XY] coordinates. f=fill(0/1)
- DRAW TRI   <aX>  <aY>  <bX>  <bY>  <cX>  <cY>  <c>   <f>            > Draws a triangle with coordinates [abc][XY].
- DRAW QUAD  <tlX> <tlY> <trX> <trY> <brX> <brY> <blX> <blY> <c> <f>  > Draws a quadrilateral, tl=Top Left, tr=Top Right, br=Bottom Right, bl=Bottom Left.
- DRAW ELLI  <Xc>  <Yc>  <Xr>  <Yr>  <c>   <q>   <f>                  > Draws an ellipse. Q=Quadrant.
                fill     = 0/1
                Quadrant = 0-3 to draw 1 of 4 quadrants.
                Quadrant = 4   to draw all 4 quadrants.

**** BLITTER must have PAGET (SRCE/DEST) set to function.

- BLIT TCOL  <transparent_color>         > [0.255]  Selects which color in the source image will be transparent when doing a paste when paste mask is enabled.
- BLIT SIZE  <px> <py> <width> <height>  > Sets the source image top left pixel position (px,py) and the copy (width,height) in pixels.
- BLIT ZOOM  <usX> <usY> <dsX> <dsY>     > Sets blitter zoom, us=upsample   float X/Y zooms up the SRCE image copy input   1.000000 to 4095.00000. (12 bit granularity)
                                                                ds=downsample float X/Y shrinks  the DEST image paste output 1.000000 to 0.000245.   (12 bit granularity)

- BLIT CONFIG  <ena>  <mask> <h-centp> <mirror> <v-centp> <flip> <r90>  <r45>

         ena       = blitter off/on             1 = blitter on when writing pixels.
                                                0 = blitter off when writing pixels.
         mask      = Transparency mask enable.  1 = source transparent color pixels will not paste pixels onto destination, IE those colors are transparent.
                                                0 = Every pixel from the source will paste onto the destination.
         h-centp   = horizontal center paste.   1 = Offset the paste to the left by half of blit_width.
                                                0 = Use the paste coordinates as the beginning left.
         mirror    = Horizontal mirror paste.   1 = Mirror the output on the X axis.
                                                0 = Off.
         v-centp   = Vertical center paste.     1 = Offset the paste up by half of blit_height
                                                0 = Use the paste coordinates as the beginning top of the paste
         flip      = Vertical flip paste.       1 = Vertically flip the output on the Y axis.
                                                0 = Off
         r90       = Enable Rotate 90 degree.   1 = Swaps the X&Y coordinates on the paste.
         r45       = Enable Rotate 45 degree.   1 = Increments/decrements the X&Y coordinates on the paste in unison.