NAME
ggi_colormap, ggi_colormap_region - LIBGGI colormap
SYNOPSIS
#include <ggi/ggi.h>
/* a color consists of red, green, blue and alpha component */
typedef struct { uint16_t r,g,b,a; } ggi_color;
/* color look up table */
typedef struct { uint16_t size; ggi_color *data; } ggi_clut;
enum ggi_colormap_region {
GGI_COLORMAP_RW_REGION = 0,
GGI_COLORMAP_RO_REGION = 1,
GGI_COLORMAP_RW_RO_REGION = 2
};
typedef int (ggifunc_setPalette)(ggi_visual_t vis,
size_t start, size_t size,
const ggi_color *cmap);
typedef struct ggi_colormap {
ggi_clut clut;
size_t rw_start;
size_t rw_stop;
size_t ro_start;
size_t ro_stop;
void *priv;
size_t (*getPrivSize)(ggi_visual_t vis);
int (*setRW)(ggi_visual_t vis, size_t start, size_t end);
int (*setRO)(ggi_visual_t vis, size_t start, size_t end);
int (*getRW)(ggi_visual_t vis, size_t *start, size_t *end);
int (*getRO)(ggi_visual_t vis, size_t *start, size_t *end);
ggifunc_setPalette* setPalette;
ssize_t (*findByColor)(ggi_visual_t vis,
const ggi_color *color,
enum ggi_colormap_region region);
ssize_t (*findByIdx)(ggi_visual_t vis,
size_t idx,
enum ggi_colormap_region region);
int (*matchByColor)(ggi_visual_t vis,
const ggi_color *color1,
const ggi_color *color2,
enum ggi_colormap_region region);
int (*matchByIdx)(ggi_visual_t vis,
size_t idx1,
size_t idx2,
enum ggi_colormap_region region);
} ggi_colormap;
/* This is a very usefull marco to directly access visual palette entry */
#define LIBGGI_PAL(vis) ((vis)->palette)
DESCRIPTION
ggi_colormap structure can be considered as an interface between target
colormap and ggi internal colormap. Target specific information is
stored in the priv member. The ggi colormap is represented by the clut
member. It can be viewed as an abstract colormap whereas the priv
member can be view as the ’real’ one. These members are initialised
during ggi initialisation. Colormaps (both target dependent and
independent ones) are updated/initialised with the ggiSetPalette
function.
The target is also responsible for setting the RO/RW area indices. RW
entries can be modified by any application whereas RO entries can’t be
modified. In a target like X (or any other windowed one) where the
colormap is shared between all the applicataion, RO entries are the
shared color cells. These colormap entries are shared by all
applications so any changes will affect them. For example if you
display a 256 colors image without taking these entries into account,
the colors of the window manager and all the other windows are screwed.
The RW entries are the private color cells (ie) application specific
entries. The reason why the RO/RW management is not a native ggi
feature is simple if we consider this almost wrong analogy. GGI can be
seen as a graphical hardware and the target as its driver. The hardware
only give us access to ’raw’ data. The way we represent/use it is up to
the target developer.
Every colormap function respect the standard ggi return policy which
is: - 0 on normal completion - >0 when giving additional hints or
returning nonnegative integer data - <0 for errors, see ggi-error(3)
STRUCTURE MEMBERS
clut The ggi side colormap.
rw_start, rw_stop
Read/Write region boundaries. Any color in this region can be
modified.
ro_start, ro_end
Read only region boundaries. Colors in this region can’t and
must not be modified.
priv Target specific informations. This could be the target colormap
structure.
getPrivSize
Return the size in bytes of the priv member.
setRW, setRO
Initialize the RW RO region of the colormap. These functions
perform target specific operations and initialize region
boundaries members of the colormap structure.
getRW, getRO
Get RW RO region information from target.
setPalette
One of the more important function. It initializes the colormap
(both internal and target ones).
findByColor, findByIdx
Find the index of the color passed as argument.
matchByColor
Match the CLUT entry with the lowest index when more than one
CLUT entry exists with the same color in it.
matchByIdx
Similar to matchByColor. The correct pixel value of the color in
the CLUT slot N is not necessarily N.
EXAMPLES
display/my_target/mode.c:
int GGI_my_target_setmode(ggi_visual *vis,ggi_mode *tm) {
/* Target structure */
ggi_my_target_priv *priv;
priv=LIBGGI_PRIVATE(vis);
/* [...] */
/*
Let’s considerer a basic vga target with two different
mode, a truecolor and a 8bpp(vga like) mode.
First you’ll have to initialize the ggi_colormap structure
during video mode initialization.
*/
if(priv->mode == MY_TARGET_8BPPINDEXED) {
/*
Well we know that the colormap can only contain 256 colors.
But that’s some kind of paranoid size computation :)
*/
LIBGGI_PAL(vis)->clut.size = 1 << priv->bits_per_pixel;
/* Let’s allocate the the clut data */
LIBGGI_PAL(vis)->clut.data = _ggi_malloc(LIBGGI_PAL(vis)->clut.size * sizeof(ggi_color));
/* Set up function pointers */
LIBGGI_PAL(vis)->getPrivSize = GGI_my_target_getPrivSize;
LIBGGI_PAL(vis)->setPalette = GGI_my_target_setPalette;
/*
If you need it initialize ggi_colormap priv member to hold
target colormaps informations.
my_target_palette is the colormap target structure.
In this example my_target_palette contains 3 arrays
of 256 bytes (b g r).
*/
LIBGGI_PAL(vis)->priv = _ggi_malloc(sizeof(my_target_palette));
}
/* [...] */
return 0;
}
/* getPrivSize */
size_t GGI_my_target_getPrivSize(ggi_visual_t vis)
{
return sizeof(my_target_palette);
}
display/my_target/color.c:
#include "config.h"
#include <ggi/internal/ggi-dl.h>
#include <ggi/display/my_target.h>
/* setPalette */
int GGI_my_target_setPalette(ggi_visual_t vis, size_t start, size_t size, const ggi_color *colormap)
{
ggi_fbdev_priv *priv = LIBGGI_PRIVATE(vis);
my_target_palette *pal = (my_target_palette*)(LIBGGI_PAL(vis)->priv);
DPRINT_COLOR("my_target setpalette.(%d,%d) %d\n",
start,size,LIBGGI_PAL(vis)->clut.size);
/*
We will consider the target library contains a colormap initialisation function
that takes a my_target_palette and two indices as arguments.
First we’ll update the ggi_colormap and our priv palette.
*/
memcpy(LIBGGI_PAL(vis)->clut.data+start, colormap, size*sizeof(ggi_color));
for(; size > 0; ++start, --size) {
pal->b[start] = LIBGGI_PAL(vis)->clut.data[start].b >> 8;
pal->g[start] = LIBGGI_PAL(vis)->clut.data[start].g >> 8;
pal->r[start] = LIBGGI_PAL(vis)->clut.data[start].r >> 8;
}
/* Then we’ll call the function provided by the target api that updates the colormap */
my_target_update_colormap(pal);
return 0;
}
SEE ALSO
ggiSetPalette(3)