Man Linux: Main Page and Category List

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)