Documentaton fixes

Index.md

@@ -1,7 +1,7 @@
 # Introduction {#mainpage}
 
 ## About this Fork
-This is a fork of the [PicoVGA project](https://github.com/Panda381/PicoVGA) created by Miroslav Nemecek (Panda38@seznam.cz).  It has been altered from the original to use the standard Linux-based Pico SDK.
+This is a fork of the [PicoVGA project](https://github.com/Panda381/PicoVGA) created by Miroslav Nemecek (Panda38@seznam.cz).  It has been altered from the original to use the standard Linux-based  Raspberry Pi Pico SDK.  The header files have also been altered to support automatically generating documentation.
 
 This fork was created to support the Pico W hardware not supported by SDK included in the original PicoVGA project.   
 
@@ -15,7 +15,9 @@ To try out the library, the simplest approach is to take 8 resistors and connect
 
 ![](www/img/PicoVGA_diagram2.jpg)
 
-*License terms*: The PicoVGA library source code and the PicoVGA library sample programs are freely available for further use and modifications. This does not apply to certain graphics and sounds (such as the sounds in Pac-Man) and scene definitions in Sokoban, as these are subject to third party copyrights and may be subject to different distribution terms.
+### License terms
+
+The PicoVGA library source code and the PicoVGA library sample programs are freely available for further use and modifications. This does not apply to certain graphics and sounds (such as the sounds in Pac-Man) and scene definitions in Sokoban, as these are subject to third party copyrights and may be subject to different distribution terms.
 
 ## Features
 
@@ -34,4 +36,3 @@ To try out the library, the simplest approach is to take 8 resistors and connect
 * The library uses the 2nd core of the processor, the 1st core is reserved for the main program 
 * Additional PWM audio output (not required)
 
-test link LayerSpriteSetup()

UsageRules.md

@@ -0,0 +1,19 @@
+# Usage Rules {#usagerules}
+
+Image generation on the Raspberry Pico is a matter of processor utilization limits and other processor activities must be subordinated to it. When using the PicoVGA library, there are several principles to keep in mind:
+
+The library always runs on the second core of the processor and the program on the first core. Rendering the image can completely overload the CPU core and is usually unusable for other use. The separation of core functions also has the advantage that the cores do not affect each other and there is no need for mutual locking. The first core simply uses write to the frame buffers and the second core displays the contents of the frame buffers without any communication between them. This makes the overall work easier and faster.
+
+If the second core is not very busy (e.g. when displaying 8-bit graphics that are simply transferred using DMA transfer), it can also be used for the main program work. However, some limitations should be taken into account - the program in the second core should not use interrupts (it would interfere with the rendering function), the interpolation unit should be used with caution (the rendering function does not save its state) and it must not disable interrupts.
+
+An important rule is that all data to be accessed by the PicoVGA library must be stored in the RAM memory. External flash memory is slow and cannot be used for rendering functions. For example, if a flash image is to be displayed, it must first be copied to a buffer in RAM, and then a pointer to the RAM copy of the image will be passed to the rendering function. If a pointer to the image in flash were passed to it, slow access to flash would cause video dropouts. In addition to images, this also applies to fonts and tile patterns, for example.
+
+The limited rendering speed must be taken into account when scheduling screen layout. Some modes render very fast (e.g. 8-bit graphics are just transferred from the frame buffer using DMA) and some modes are very rendering intensive - e.g. rendering sprites in slow mode. When using demanding rendering, some video lines may not render fast enough in the required time and the video image will break (drop out of sync). In such cases, it is necessary to use another mode, or to reduce the rendered area (add other modes, faster ones - e.g. add tile controls on the sides of the screen), reduce the screen resolution or increase the CPU clock speed. Video lines are rendered separately and therefore it is always just content on one video line about, video lines do not affect each other. For example, you can test the speed of sprite rendering by placing all the sprites horizontally next to each other (the most challenging case) and check if the video synchronization fails.
+
+Care must also be taken when using DMA transfer. DMA is used to transfer data to the PIO. Although the transfer uses a FIFO cache, using a different DMA channel may cause the render DMA channel to be delayed and thus cause the video to drop out. A DMA overload can occur, for example, when a large block of data in RAM is transferred quickly. However, the biggest load is the DMA transfer of data from flash memory. In this case, the DMA channel waits for data to be read from flash via QSPI and thus blocks the DMA render channel.
+
+The CPU clock frequency must also be subordinated to the image generator. Before initializing the video node, the library calculates the required system clock frequency so that the timing matches the requirements and the processor speed is sufficient for the required image resolution. It is a good idea to initially print out the calculated clock frequency for checking on the console. It is possible to prohibit the library from changing the system clock, or to prescribe only a certain range, in which case some modes may be unreachable (or the video image may break up).
+
+Image buffers must be aligned to 4 bytes (32-bit CPU word) and image segments must be horizontally aligned to 4 pixels - this refers to the horizontal position of the segment, its width, alignment (wrapx) and offset (offx). Alignment does not apply to the vertical direction. This restriction is necessary because the image information is transferred to the PIO controller using a 32-bit DMA transfer, and this must be aligned to a 32-bit word. One 32-bit word contains 4 pixels (1 pixel has 8 bits), so the horizontal data in the image must also be aligned to 4 pixels. So you cannot do fine horizontal scrolling of the image in 1 pixel increments (the restriction does not apply to vertical scrolling), but only in 4 pixel increments. The exception to this is slow sprites, which are software rendered to the video line and can therefore be scrolled in 1 pixel increments. Similarly, the restriction does not apply to software rendering to framebuffer (e.g. rendering an image to video memory can be done to any coordinate).
+
+The display of the image by the PicoVGA library is performed by the PIO controller (PIO0).  The other controller, PIO1, is unused and can be used for other purposes. 

Wiring.md

@@ -0,0 +1,11 @@
+# Wiring diagram    {#wiring}
+
+I don't present here the overall circuit I used, because the library was created as part of a retro gaming computer with Raspberry Pico and is still under development. Here is a simplified wiring diagram of the VGA monitor output (with added audio PWM output):
+
+![](www/img/PicoVGA_diagram.jpg)
+
+The synchronization output is in the format of the CSYNC synchronization mix (composite synchro, HSYNC + VSYNC). Computer monitors support CSYNC mixed sync. The signal is fed to the HSYNC input (also referred to as CSYNC). An audio output is fed to the VSYNC pin of the VGA connector, for case of output to the TV. The VGA monitor has an input impedance of 75 ohms on this pin, this causes the audio signal to be attenuated and ignored by the VGA monitor and not considered as vertical sync. When the audio connector is inserted, the output to the VGA monitor is disconnected and the audio signal is output to the outside (e.g. to audio headphones).
+
+The TV is connected to the VGA output via a reduction that simply connects the pins of the VGA connector to the corresponding pins of the SCART connector. In this case, the audio signal fed to the VGA connector is also used. Thus, it is not necessary for the device to include a special connector for the TV. The 5V voltage from pin 9 is used as the control voltage for the SCART connector - pin 16 of the SCART connector (Blanking) is connected via a 100 ohm resistor and pin 8 (Switch) is connected directly.
+
+The keyboard connection is not draw here. All sample programs are set up so that program control can be used via the console on the USB virtual port. Simply connect the Pico to the PC via the USB cable used for programming, and run a console program that connects to the USB virtual COM port. For a more detailed description of the connection, see the SDK description.

doxygen.cfg

@@ -971,7 +971,7 @@ EXAMPLE_RECURSIVE      = NO
 # that contain images that are to be included in the documentation (see the
 # \image command).
 
-IMAGE_PATH             =
+IMAGE_PATH             = www/img
 
 # The INPUT_FILTER tag can be used to specify a program that doxygen should
 # invoke to filter for each input file. Doxygen will invoke the filter program

src/util/canvas.h

@@ -13,16 +13,16 @@
 /**
  * @addtogroup CanvasGroup
  * @brief Drawing board for shapes and images
- * @details Canvas is a drawing board. It is a support library for working with graphical surfaces and images (see the canvas.h 
- * file in the _picovga\util folder). The sCanvas structure is a set of parameters that describe the graphical surface, for use 
+ * @details Canvas is a drawing board. It is a support library for working with graphical surfaces and images. 
+ * The sCanvas structure is a set of parameters that describe the graphical surface, for use 
  * in drawing functions. A graphical surface can be either a graphical frame buffer or an image, even in Flash. To draw in a 
  * graphical surface, first attach a canvas to it as a definition describing the structure of the area. Likewise, if you want 
  * to draw an image to the surface, first create a canvas for the image with its parameters. The parameters are a pointer to
  * the image data, the image dimensions, and the format. The drawing area can be a graphic area with a depth of 1, 2, 4, 8 bits 
  * or with attributes. In the case of drawing an image to a canvas, the source and target canvas must have the same format. 
  * In the case of transformation matrices, only an 8-bit graphic format can be drawn.
- * @note In PicoVGA, a default canvas 'Canvas' is available. A graphic frame buffer is automatically attached to it when 
- * initialized with the Video function. Otherwise, it can be used arbitrarily in the program.
+ * @note In PicoVGA, a default canvas @link Canvas @endlink is available. A graphic frame buffer is automatically attached to it when 
+ * initialized with the Video() function. Otherwise, it can be used arbitrarily in the program.
  * @{
 */
 

src/util/overclock.h

@@ -15,7 +15,7 @@
  * @details Some display functions may be CPU speed intensive and may require overclocking to a higher speed. It should be 
  * understood that overclocking places the processor in areas where proper function is not guaranteed. The PicoVGA library 
  * allows you to control the overclocking of the processor, according to the desired video mode. The minimum and maximum 
- * processor frequency can be specified in the VgaCfg function. By default, the library allows a range of 120 to 270 MHz. 
+ * processor frequency can be specified in the VgaCfg() function. By default, the library allows a range of 120 to 270 MHz. 
  * However, it may happen that at higher frequencies the processor will not operate correctly and it may be necessary to 
  * lower the upper limit.
  * The searched processor frequency can be set with the set_sys_clock_pll() function.

src/vga.h

@@ -118,6 +118,7 @@ void VgaInit(const sVmode* vmode); //, u8 layer1mode=LAYERMODE_BASE, u8 layer2mo
  * @addtogroup VideoInitGroup
  * @brief Functions for initialzing the library
  * @details The video mode can be initialized either simply by the Video() function or in more detail by the following functions.
+ * @see VideoModeGroup
  * @{
 */
 
@@ -136,6 +137,7 @@ void StartVgaCore();
  * is necessary to first stop the video generation by calling the VgaInitReq function with the NULL parameter, and 
  * only then call the function with the new video mode setting.
  * @param vmode Video format description generated by VgaCfg() or NULL to stop driver.
+ * @see VideoModeGroup
 */
 void VgaInitReq(const sVmode* vmode);
 

src/vga_screen.h

@@ -11,7 +11,7 @@
 /**
 * @addtogroup ScreenGroup
 * @brief Defining the layout of the display
-* @details When displaying screen image, the default pointer is pScreen for the library. It points to the sScreen structure that 
+* @details When displaying screen image, the default pointer is @link pScreen @endlink for the library. It points to the sScreen structure that 
 * describes the contents of the display. The Raspberry Pico has a limited RAM size and cannot accommodate a high resolution image. 
 * Therefore, the image must be composed of smaller segments to minimize the memory-intensive parts.
 * @note The following descriptions of the image format only apply to the base image layer 0. It is the only one that can contain 

src/vga_vmode.h

@@ -246,6 +246,7 @@ void VgaPrintCfg(const sVmode* vmode);
  * @brief Calculate the structure for setting up the video mode.
  * @param cfg Source configuration structure
  * @param vmode Destination videomode setup for driver
+ * @see VgaInitReq()
 */
 void VgaCfg(const sVgaCfg* cfg, sVmode* vmode);