Writing to VRAM
===============

To update graphics using resource component data,
you need the "std_bfr" library (graphics library) included
in the project.

ScreenOn VRAM Buffers
---------------------

The most important thing is that in ScreenOn
mode (when display is on), you must NOT use any
macro/routine that writes directly to VRAM. This will
likely screw up the screen. However, in screenon mode, VRAM can
be updated from the NMI Innterupt.
The graphics library has PPU buffers that can be
used in your processes to update graphics when display is on.
The procedure is following: You use any of the macros that
come with the buffer library to set up the buffer memory,
then you set its trigger memory to have it used in the NMI.
The graphics library will then use the buffer memory to
write to VRAM when NMI is executed.

ScreenOff VRAM Writes
---------------------

In ScreenOff mode, you can use macros in the graphics library
to write directly to VRAM (instead of buffering around).

You can ofcourse also use ScreenOn macros in ScreenOff mode,
but you have to use macros to manually write from buffers to
VRAM (or call the NMIEnforce macro to force a NMI).

Standard VRAM Buffers
---------------------

Name                   Trigger             Usage

Palette Buffer         palette_update      Palette Resources
String Buffer          string_write        String Blocks
Construction Buffer    constr_write        Constructions
CVB Buffer             cvb_write           Constructions (special for NMI update)

Palette Buffer / Macros
-----------------------

In memory is reserved -two- different chunks
of palette memory. (each on $20 bytes)
One for keeping the
current palette in memory, another the
buffer for writing to the PPU.

This dual-memory system is useful when you need to update the
palette -based- on itself, for example
palette fading up and down.

ScreenOn Macros:

	palload_source (palload_source <source>, ![<source_start>],![<dest_start>],![<size>])

This will load from any memory address (<source>) to the
palette source memory.

ScreenOff Macros:

	palwrite_buffer (palwrite_buffer)

Write to VRAM directly from palette buffer memory.

	palwrite_srcmem (palwrite_srcmem)

This will write from the palette_source memory to
both palette_buffer memory and VRAM.

	palwrite_source (palwrite_source <source>, ![<source_start>],![<dest_start>],![<size>])

This will write directly to VRAM from a memory adress.

Strings
-------

ScreenOn Macros:

	strbuffer_source (strbuffer_source <source>)

Copy from any memory adress to the string buffer.

ScreenOff Macros:

	strwrite_source (strwrite_source <source>)

Write directly to VRAM from a source.

	strwrite_buffer (strwrite_buffer)

Write directly to VRAM from the string buffer.

Constructions
-------------

ScreenOn Macros:

	cvbbuffer_source (constrcvb_source <source>)

Create the CVB based on  a construction resource.

	cvbbuffer_constrbfr (constrcvb_constrbfr)

Create the CVB based on the construction buffer.

	constrbuffer_source (constrbuffer_source <source>)

Copy from a resource to the construction buffer.

ScreenOff Macros:

	constrwrite_source (constrwrite_source)

Write directly to VRAM based on a construction resource.

	constrwrite_buffer

Write directly to VRAM based on the construction buffer.

	cvbwrite_buffer

Write to VRAM based on the CVB buffer.

Procedure
---------

Each buffer uses a 'trigger' thats set to 1 when the buffer should be used to
write to VRAM in NMI.
When updating VRAM using a buffer, you should use Waitcl to wait until the trigger is
clear (in case some other process used the buffer first). Then, use any of the macros
to set up the buffer, finnaly, set the trigger to 1.

This can be done for example this way (for a string):

	stateset
	waitcl	string_write
	strbuffer_source	string_instructions
	inc	string_write