NAME
ggi_directbuffer, ggi_pixellinearbuffer, ggi_pixelplanarbuffer,
ggi_samplelinearbuffer, ggi_sampleplanarbuffer - LibGGI direct buffer
structure description
SYNOPSIS
#include <ggi/ggi.h>
typedef struct {
uint32_t type;
int frame;
ggi_resource_t resource;
void *read;
void *write;
unsigned int page_size;
uint32_t noaccess;
uint32_t align;
ggi_bufferlayout layout;
union {
ggi_pixellinearbuffer plb;
ggi_pixelplanarbuffer plan;
ggi_samplelinearbuffer slb;
ggi_sampleplanarbuffer splan;
void *extended;
} buffer;
} ggi_directbuffer;
DESCRIPTION
The ggi_directbuffer structure contains information on target-dependent
buffers to allow applications to access them directly.
STRUCTURE MEMBERS
type
/* Buffer types */
#define GGI_DB_NORMAL 0x0001 /* "frame" is valid when set */
#define GGI_DB_EXTENDED 0x0002
#define GGI_DB_MULTI_LEFT 0x0004
#define GGI_DB_MULTI_RIGHT 0x0008
/* Flags that may be or’ed with the buffer type */
#define GGI_DB_SIMPLE_PLB 0x01000000
/* GGI_DB_SIMPLE_PLB means that the buffer
has the following properties:
type == GGI_DB_NORMAL
read == write
noaccess == 0
align == 0
layout == blPixelLinearBuffer
*/
frame is the frame number as used in multiple buffering. Note that
each frame can export more than one DirectBuffer.
resource
is a pointer to a lowlevel resource. Certain DirectBuffers need
to be explicitly acquired (i.e. locked) before using them (i.e.
accessing their pointers). Such a situation may arise if the
underlying visual supports mixed acceleration and framebuffer
access, but they cannot occur at the same time. In that case,
LibGGI needs to be informed when the application is using the
framebuffer.
You can determine whether the DirectBuffer needs to be acquired
by using ggiResourceMustAcquire(3). An acquire is done by using
ggiResourceAcquire(3) and it is released by calling
ggiResourceRelease(3).
read, write
are the addresses where the buffer is mapped to the application.
Read and write access to the buffer is done using load and store
instructions of the host CPU. Read operations should be
performed using the read buffer and write operations should be
performed using the write buffer. These might be the same, but
need not. If they are, read/write may be done to either buffer.
Please note, that either read or write may be NULL. These are
write-only or read-only buffers, which might be caused by
hardware limitations. Such buffers are not suited to do Read-
Modify-Write operations, so take care.
Be aware that these fields may be changed by an acquire, and
that they may be NULL or invalid when the DirectBuffer is not
acquired.
page_size
indicates a Paged buffer if not 0.
Successive access to addresses addr0 and addr1 of either read or
write buffers with addr0/page_size != addr1/page_size may be
very expensive compared to successive accesses with
addr0/page_size == addr1/page_size.
On i386 the penalty will be about 1500 cycles plus 4 cycles per
to be remapped. Because of this, block transfer operations might
become very inefficient for paged buffers. If there are two
different buffers provided for read and write operations, you
should do successive reads from one and do successive writes to
the other. If not, it is recommended to copy pagewise into a
temporary buffer and then to copy this temporary buffer back to
screen.
noaccess
is a bitfield specifying an access restriction. When bit x is
set, you may not access this DirectBuffer at the width of 2^x
bytes. It is usually 0, but check it.
align is a bitfield specifying another access restriction. When bit x
is set, you may only access this DirectBuffer at the width of
2^x bytes, when the access is aligned to a multiple of 2^x. Note
that bit 0 is a bit bogus here, but it should be always 0, as
then ((noaccess|align)==0) is a quick check for "no
restrictions".
layout is an enumeration specifying the buffer addressing scheme.
Possible values are blPixelLinearBuffer, blPixelPlanarBuffer,
blExtended, blSampleLinearBuffer and blSamplePlanarBuffer. See
below for their definition.
buffer is a union of all buffer info. Check the layout member to see
which member of use.
PIXEL LINEAR BUFFER
typedef struct {
int stride; /* bytes per row */
ggi_pixelformat *pixelformat; /* format of the pixels */
} ggi_pixellinearbuffer;
A linear buffer is a region in the application’s virtual memory address
space. A pixel with the pixel coordinates (x, y) is assigned a pixel
number according to the following formula:
pixel_number = (origin_y + y) * stride + origin_x + x;
In any case both x and y must not be negative, and less than the
buffer’s width and height respectively. For top-left-origin screen
coordinates, stride and origin_y will both be positive. For bottom-
left-origin screen coordinates, stride and origin_y will both be
negative. This will result in the correct pixel number with the same
formula in both cases. The pixel number will be used to address the
pixel.
A certain number of bits is stored per pixel, and this is indicated in
the ggi_pixelformat.access field. For some visuals, the buffer might
not be in host CPU native format and swapping operations need to be
performed before writes or after reads.
PIXEL PLANAR BUFFER
typedef struct {
int next_line; /* bytes until next line */
int next_plane; /* bytes until next plane */
ggi_pixelformat *pixelformat; /* format of the pixels */
} ggi_pixelplanarbuffer;
SAMPLE LINEAR BUFFER
typedef struct {
int num_pixels; /* how many pixelformats */
int stride; /* bytes per row */
ggi_pixelformat *pixelformat[4];/* format of the pixels */
} ggi_samplelinearbuffer;
SAMPLE PLANAR BUFFER
typedef struct {
int next_line[3]; /* bytes until next line */
int next_plane[3]; /* bytes until next plane */
ggi_pixelformat *pixelformat[4];/* format of the pixels */
} ggi_sampleplanarbuffer;
EXTENDED BUFFER
TODO : write something here.
SEE ALSO
ggi_pixelformat(3), ggiDBGetBuffer(3), ggiResourceAcquire(3)