diff --git a/DoxygenLayout.xml b/DoxygenLayout.xml index 7d4a66d..bb5e4c7 100644 --- a/DoxygenLayout.xml +++ b/DoxygenLayout.xml @@ -167,7 +167,7 @@ - + diff --git a/doxygen.cfg b/doxygen.cfg index e97ae77..0af8136 100644 --- a/doxygen.cfg +++ b/doxygen.cfg @@ -38,7 +38,7 @@ PROJECT_NAME = "PicoVGA" # could be handy for archiving the generated documentation or if some version # control system is used. -PROJECT_NUMBER = 1.0 +PROJECT_NUMBER = "1.0-cmake" # Using the PROJECT_BRIEF tag one can provide an optional one line description # for a project that appears at the top of each page and should give viewer a @@ -51,7 +51,7 @@ PROJECT_BRIEF = "VGA/TV display on Raspberry Pico" # pixels and the maximum width should not exceed 200 pixels. Doxygen will copy # the logo to the output directory. -PROJECT_LOGO = +PROJECT_LOGO = logo.png # The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) path # into which the generated documentation will be written. If a relative path is diff --git a/logo.png b/logo.png new file mode 100644 index 0000000..8ad0815 Binary files /dev/null and b/logo.png differ diff --git a/src/define.h b/src/define.h index 8012dcf..9487c0f 100644 --- a/src/define.h +++ b/src/define.h @@ -10,7 +10,7 @@ #define BLACK_MAX MAXX // size of buffer with black color (used to clear rest of unused line) -/// @addtogroup Layers Overlay Layers +/// @addtogroup LayersGroup /// @{ // VGA PIO program diff --git a/src/util/pwmsnd.h b/src/util/pwmsnd.h index b51d86f..90fdeac 100644 --- a/src/util/pwmsnd.h +++ b/src/util/pwmsnd.h @@ -10,11 +10,6 @@ // PWM sound output // // **************************************************************************** -// Sounds are at format 8-bit unsigned (middle at 128), 22050 samples per second, mono -// PWM cycle is 256: TOP = 255 -// Required PWM clock: 22050*256 = 5644800 Hz - -// GP19 ... MOSI + sound output (PWM1 B) #ifndef _PWMSND_H #define _PWMSND_H diff --git a/src/vga_layer.h b/src/vga_layer.h index de60b9f..030c4f8 100644 --- a/src/vga_layer.h +++ b/src/vga_layer.h @@ -77,21 +77,117 @@ extern u8 LayerMask; // mask of active layers /** * @addtogroup LayersGroup * @details The display of the image by the PicoVGA library is performed by the PIO processor controller. PIO0 is used. - * The other controller, PIO1, is unused and can be used for other purposes. PIO0 contains a 4 state machine, SM0 to SM3. + * The other controller, PIO1, is unused and can be used for other purposes. PIO0 contains a 4 state machines, SM0 to SM3. * All PIO0 state machines use a common program of 32 instructions. Each state machine serves 1 overlay layer. SM0 services * base layer 0, along with servicing the synchronization signal. The base layer service program consists of 15 instructions, - * starting at offset 17. This part of the program is immutable and is always used. The other 3 layers, 1 to 3, SM1 to SM3, + * starting at offset 17. This part of the program is immutable and is always used. However, the other 3 layers, 1 to 3, SM1 to SM3, * use the other part of the program memory, 17 instructions starting at address 0. This part may change, depending on the mode * of the overlay layers. All 3 overlay layers use a common program and must therefore operate in the same display mode. Some * overlay modes use the same program and can be shared - see the table below for details. * @note Only base layer 0 can contain segments in different formats. Overlay layers 1 to 3 are independent of the base layer * format, sharing only the total display area with the base layer, but using their own image format, for which only the * coordinates and dimensions are specified. - * @par - * Overlay layers can use one of the following programs: + * + *

Overlay layers can use one of the following programs:

* * LAYERPROG_BASE - The base layer 0 program. Cannot be used for overlay layers. Using the parameter * for an overlay layer means that the layer is inactive (not using the program). * * LAYERPROG_KEY - Layer with key color. The specified color is replaced by transparency. + * * LAYERPROG_BLACK - Transparency with black color. Black is replaced by transparency. Compared to the previous mode, + * the advantage is less demanding on processor speed. + * * LAYERPROG_WHITE - transparency with white colour. It is faster like the previous function and is suitable for use + * where black needs to be preserved but white can be omitted. When preparing the image, the image is not copied from Flash to + * RAM with the memcpy function, but the CopyWhiteImg() function is used. The function ensures that the pixels of the copied + * image are incremented by 1. This changes the white color (with a value of 255) to black (with a value of 0). From this point + * on, the image is treated as if it had transparency with black - e.g. the black color is specified for the sprite rendering + * function. Only when the image enters the program in PIO0, the program makes the pixel transparent as in the case of black, + * but at the same time decrements the pixel value. This reverts the colors back to the original value, the black color becomes + * black and the white color has been used as transparency. + * * LAYERPROG_MONO - This programme includes 2 sub-programmes. The first is the display of a monochrome image. For each + * bit of image data, either the selected image color is displayed or the corresponding pixel is transparent. This mode is used + * in the Oscilloscope example to display a grid across the oscilloscope screen. The second subroutine is to display a color + * image without transparency. The color pixels are displayed as they are, with no transparency option, but the dimensions of + * the image rectangle and its coordinate on the display can be defined. Thus, a sort of analogy of a single rectangular sprite + * without transparency. + * * LAYERPROG_RLE - RLE compression mode. RLE compression is not a universally valid format. It means that the data + * contains segment length information. In this case, the image data of PicoVGA library contain directly instructions for the + * PIO program. More specifically, the image data is interleaved with the jump addresses inside the program. The image is + * prepared using the RaspPicoRle program and is strongly coupled to the layer program used. If, for example, the instructions + * in the program were shifted, the RLE compression format would stop working. This is also why the program for base layer 0 + * is placed at the end of the program memory and the overlay layer programs at the beginning - to reduce the chance that + * changes in the program will change the location of the program in memory, at which point RLE compression would stop working. + * After modifying the RLE program in PIO, the conversion program must also be updated. + * + * The desired mode of each overlay layer is specified in the video mode definition using the VgaCfg() function. The layer mode + * is used to derive the program and function used to operate the layer rendering. Multiple layer modes can share the same + * program type. Layer modes have different state machine timing requirements. The configuration function takes this into + * account and adjusts the processor frequency accordingly. + * + *

Modes of overlay layers:

+ * + * *WHITE modes using white transparent color require image preparation using CopyWhiteImg() as specified for LAYERPROG_WHITE. + * * LAYERMODE_BASE - Indicates base layer mode 0. Cannot be used for an overlay layer, but is used to indicate an inactive + * disabled overlay layer. + * * LAYERMODE_KEY - The layer with the specified key color. + * * LAYERMODE_BLACK - Layer with black key color. + * * LAYERMODE_WHITE - Layer with white key color. + * * LAYERMODE_MONO - Monochromatic image. + * * LAYERMODE_COLOR - Colour image (without transparency). + * * LAYERMODE_RLE - Image with RLE compression. + * * LAYERMODE_SPRITEKEY - Sprays with the specified key color. + * * LAYERMODE_SPRITEBLACK - Sprays with black key color. + * * LAYERMODE_SPRITEWHITE - Sprays with white key color. + * * LAYERMODE_FASTSPRITEKEY - Fast sprites with the specified key colour. + * * LAYERMODE_FASTSPRITEBLACK - Fast sprites with black key colour. + * * LAYERMODE_FASTSPRITEWHITE - Fast sprites with white key colour. + * * LAYERMODE_PERSPKEY - Image with transformation matrix with specified key color. + * * LAYERMODE_PERSPBLACK - Image with transformation matrix with black key color. + * * LAYERMODE_PERSPWHITE - Image with transformation matrix with white key color. + * * LAYERMODE_PERSP2KEY - Image with transformation matrix with specified key color and doubled width. + * * LAYERMODE_PERSP2BLACK - Image with transformation matrix with black key color and doubled width. + * * LAYERMODE_PERSP2WHITE - Image with transformation matrix with white key color and doubled width. + * + *

Shared overlay modes

+ * + * Layer modes can only be combined together if they use the same program. CPP is the minimum required number of SMx clock + * cycles per pixel. + * | |PROG_BASE |PROG_KEY |PROG_BLACK |PROG_WHITE |PROG_MONO |PROG_RLE |CPP | + * |----------------------------|:---------:|:---------:|:---------:|:---------:|:---------:|:---------:|:-----:| + * |LAYERMODE_BASE | X | | | | | | 2 | + * |LAYERMODE_KEY | | X | | | | | 6 | + * |LAYERMODE_BLACK | | | X | | | | 4 | + * |LAYERMODE_WHITE | | | | X | | | 4 | + * |LAYERMODE_MONO | | | | | X | | 4 | + * |LAYERMODE_COLOR | | | | | X | | 2 | + * |LAYERMODE_RLE | | | | | | X | 3 | + * |LAYERMODE_SPRITEKEY | | X | | | | | 6 | + * |LAYERMODE_SPRITEBLACK | | | X | | | | 4 | + * |LAYERMODE_SPRITEWHITE | | | | X | | | 4 | + * |LAYERMODE_FASTSPRITEKEY | | X | | | | | 6 | + * |LAYERMODE_FASTSPRITEBLACK | | | X | | | | 4 | + * |LAYERMODE_FASTSPRITEWHITE | | | | X | | | 4 | + * |LAYERMODE_PERSPKEY | | X | | | | | 6 | + * |LAYERMODE_PERSPBLACK | | | X | | | | 4 | + * |LAYERMODE_PERSPWHITE | | | | X | | | 4 | + * |LAYERMODE_PERSP2KEY | | X | | | | | 6 | + * |LAYERMODE_PERSP2BLACK | | | X | | | | 4 | + * |LAYERMODE_PERSP2WHITE | | | | X | | | 4 | + * + *

Selection of write planes

+ * + * By default, the image is output from the layers to all output pins. This can be changed by redefining the LayerFirstPin + * and LayerNumPin fields (in vga_layer.cpp). It is possible to specify for each layer separately which output pins will + * be written to. This can create a kind of pseudo-transparency. For example, one layer will render curves in red, another + * layer in green, and the colors will blend independently. When redefining the pins, however, you must take into account + * that the offset of the pin mapping will shift. The output will always start from the lowest bits of the pixel. + * + *

Configure overlay layers

+ * + * The first step for setting up the overlay layer is to specify the layer mode for the VgaCfg() initialization function. + * The function detects the required program and the required timing. It does not check if the correct layer modes are + * combined together. + * + * The second step is to initialize the layer descriptor - the sLayer structure in the LayerScreen field. It is convenient + * to use the LayerSetup() initialization function for this. * @{ */