A program can operate in a 'palette' color mode or in a 'static' color mode, depending on the presence of a modifiable color palette in the graphic system.
Palette mode is normally available when the number of colors simultaneusly viewable is small (typically 16 or 256), and the graphic card is capable of a wide range of selectable colors (256K in the standard VGA). When operating in this mode, the pixel value in the video memory is used as an index by the display adapter to address a table containing the actual R-G-B values of the pixel color. By using 8 bit per pixel (planes) it's possible to address 256 different entries in the table and any combination of R-G-B values (256K in the standard VGA) can be assigned to each entry (palette cell).
This mode is efficient because it permits you to select colors in a wide range of available ones. Moreover it makes it possible to realize color animation by simply changing R-G-B values in the palette.
In the static mode the graphic system operates with a fixed color palette. This can be achieved in 16 color mode under Windows or in HiColor mode which offers 15, 16 or 24 bit per pixel with respectively 32K, 64K or 16M colors. HiColor mode grants a superior photographic resolution, but reaches slower performances because it requires 2 or 3 byte to code a single pixel while the palette mode with 256 colors needs only one byte.
If the MGUI application does not require color animation, it can actually ignore both the number of available colors and the operating color mode (palette or static).
If the application wants to know some details about the graphic environment in which it operates, it can call the MPaletteMode() function which returns 'True' if the palette mode is on. The MGetNColors() function returns the number of simultaneously viewable colors in the system and MGetNPlanes() returns the number of color planes.
Before using a color, the program must allocate it in the library. There are several allocation functions, each returning the color identifier that can be used in the drawing functions or to set a new color to an Object. The MAllocColor() function allocates a color specified by the three argument values (in the range 0-255) identifying the R-G-B color components. When the color is no longer needed, it should be freed via a call to the function MFreeColor().
Palette Mode
When operating in palette mode, a copy of the video palette is hold in memory by the library with a counter and a status flags for each entry (color cell). If so, a color identifier is equivalent to a cell index. Each counter value is initially set to zero and the status flag to 'free'. As a color allocation request occurs, the following situations can be in effect:
If none of the already used cells contains the desired R-G-B values but there is a free cell, it's status is set to 'used', the counter to 1 and cell R-G-B values are filled in with the requested ones. The cell index is returned as the new color identifier. If there is a cell containing the desired R-G-B values, then its counter is incremented by one and its index is returned as the color identifier. Finally, if no cell contains the desired R-G-B values and there are no free cell available, then the library computes which is the cell whose R-G-B values are closest to the requested ones, increments its counter and finally returns the cell index as the color identifier.
When a color is freed, the corresponding palette index counter is decremented by one. Moreover, if the counter reaches the zero value, the cell flag is reset to 'free' and the palette entry becomes available for further allocations.
This handling policy grants an optimal use of the palette resource, provided that the application correctly frees all no longer needed colors.
In order to obtain the palette animation feature, the application should reserve one or more palette cells for this purpose via the MAllocCell() function call. In this case the cell becomes 'reserved' and its R-G-B values can be set at any time by using the MSetCellColor() function call. Moreover its index is not used by the library for successive color allocation requests, until the program frees the cell using the MFreeCell() function.
If there are no free cells available, MAllocCell() returns, as an error, the black color identifier. In this case, any attempt to set the cell R-G-B values will obviously fail.