ggi_directbuffer

Section: GGI (3)
Updated: 2006-12-30
Page Index

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.