From: Marcus Sundberg <e94_msu@e.kth.se>
  To  : ggi-develop@eskimo.com
  Date: Tue, 04 Aug 1998 18:36:22 +0200

ggiGetPixelFormat and proposed new DirectBuffer scheme

Hi!

I've been hacking some headers and here's what I propose:

/* Pixelformat for ggiGet/Put buffers etc. */
typedef struct {
	int		bits;		/* Number of significant bits */
	int		size;		/* Physical size in bits */

	ggi_pixel	red_mask;	/* Bitmask of red bits */
	ggi_pixel	green_mask;	/* Bitmask of green bits */
	ggi_pixel	blue_mask;	/* Bitmask of blue bits */
	ggi_pixel	alpha_mask;	/* Bitmask of alphachannel bits */

	ggi_pixel	clut_mask;	/* Bitmask of bits for the clut */
	ggi_pixel	fg_mask;	/* Bitmask of foreground color */
	ggi_pixel	bg_mask;	/* Bitmask of background color */
	ggi_pixel	texture_mask;	/* Bitmask of the texture (for
					   textmodes - the actual character) */
	uint32		flags;		/* Pixelformat flags */
} ggi_pixelformat;

/* Pixelformat flags */
#define GGI_PF_REVERSE_ENDIAN	0x01
#define GGI_PF_HIGHBIT_LEFT	0x02
#define GGI_PF_HIGHBIT_RIGHT	0x04

(The alpha_mask is unused but exists for compability with
higher level libs, just like the "a" entry in ggi_color)

The ggi_info struct and ggiGetInfo() will be removed completely.
The information in it is now supplied by the old functions:
ggiDBGetBuffer(), ggiGetMode() and ggiGetFlags()
and the new functions:
const ggi_pixelformat *ggiGetPixelFormat(ggi_visual_t vis);
int                    ggiGetSelectFD(ggi_visual_t vis);

The GGI_PF_* flags will also be used for the subscheme in
ggi_graphtype.

This scheme is accompanied by a new DirectBuffer scheme
which is cleaner, simpler to use and still supports all
features of libggi:


/***************************************************************
 * DirectBuffer
 ***************************************************************/

typedef enum {
	blPixelLinearBuffer,
	blExtended,

	blLastBufferLayout
} ggi_bufferlayout;

typedef struct {
	int		stride;		/* bytes per row		*/
	ggi_pixelformat *pixelformat;	/* format of the pixels		*/
} ggi_pixellinearbuffer;

/* Buffer types */
#define GGI_DB_NORMAL		0x01
#define GGI_DB_EXTENDED		0x02
#define GGI_DB_MULTI_LEFT	0x04
#define GGI_DB_MULTI_RIGHT	0x08

typedef struct {
	int		frame;		/* framenumber */
	uint32		type;		/* buffer type */
 
	/*	access info	*/
	void		*read;		/* buffer address for reads	*/
	void		*write;		/* buffer address for writes	*/
	unsigned int	access;		/* supported access widths	*/
	unsigned int	align;		/* alignment requirements	*/
	unsigned int	page_size;	/* zero for true linear buffers	*/

	ggi_bufferlayout	layout;

	/* The actual buffer info. Depends on layout. */
	union {
		ggi_pixellinearbuffer plb;
		void *extended;
	} buffer;
} ggi_directbuffer;

typedef struct {
	void		*fbaddr;	/* address of the framebuffer	*/
	int		stride;		/* bytes per row		*/
	ggi_pixelformat *pixelformat;	/* format of the pixels 	*/
} ggi_simpleplb;

/* DB functions
*/
int  ggiDBGetSimplePLB(ggi_visual_t vis, ggi_simpleplb plb);
int  ggiDBGetNumBuffers(ggi_visual_t vis);
const ggi_directbuffer *ggiDBGetBuffer(ggi_visual_t vis, int bufnum);


The blExtended bufferlayout allows every possible buffer to
be supported by an extensionlibrary.

The frame entry is the framenumber (when double/tripplebuffering)
The type entry contains one or more GGI_DB_* flags.
This allows for things like doublebuffering on a pair of
VR-goggles (in which case ggiDBGetNumBuffers() would return 4
and we'd have two GGI_DB_MULTI_LEFT and two GGI_DB_MULTI_RIGHT
buffers)

ggiDBGetSimplePLB() will return a buffer with the following
properties:
frame=1
type=GGI_DB_NORMAL
read=write
access=all widths supported by the host CPU
align=any supported by the host CPU
layout=blPixelLinearBuffer

If no such buffer exists it will fail, and the user'll have to use
the regular ggiDBGetBuffer()

Please give comments/improvements on this scheme so we can
replace the old DirectBuffer stuff as soon as possible.

//Marcus
-- 
-------------------------------+------------------------------------
        Marcus Sundberg        | http://www.stacken.kth.se/~mackan/
 Royal Institute of Technology |       Phone: +46 707 295404
       Stockholm, Sweden       |      E-Mail: e94_msu@e.kth.se