Man Linux: Main Page and Category List

NAME

       ggiDBGetNumBuffers, ggiDBGetBuffer - Get DirectBuffers from a visual

SYNOPSIS

       #include <ggi/ggi.h>

       int  ggiDBGetNumBuffers(ggi_visual_t vis);

       const ggi_directbuffer *ggiDBGetBuffer(ggi_visual_t vis, int bufnum);

DESCRIPTION

       Dependent on the visual and runtime environment found, applications may
       be granted direct access to hardware and/or library  internal  buffers.
       This  may  significantly enhance performance for certain pixel oriented
       applications or libraries.

       The DirectBuffer is a mechanism in which a LibGGI program  can  use  to
       determine  all  the  characteristics  of  these  buffers (typically the
       framebuffer), including the method of addressing, the stride, alignment
       requirements, and endianness.

       However,  use  not conforming to this specification will have undefined
       effects and may cause data loss or corruption, program  malfunction  or
       abnormal program termination. So you don’t really want to do this.

       ggiDBGetNumBuffers returns the number of DirectBuffers available to the
       application.  ggiDBGetBuffer obtains the DirectBuffer at the  specified
       position.

       Use  ggiDBGetBuffer to obtain the DirectBuffers at 0 to n-1, where n is
       the number returned by ggiDBGetNumBuffers.

       Pixel-linear  buffers  have  type==GGI_DB_SIMPLE_PLB  |  GGI_DB_NORMAL.
       You’re on your own now.

       DirectBuffers  where  ggiResourceMustAcquire(3)  is  true  need  to  be
       acquired (i.e. locked) before using.   An  acquire  is  done  by  using
       ggiResourceAcquire(3) and is released by calling ggiResourceRelease(3).
       Beware that the read, write and stride fields of the  DirectBuffer  may
       be changed by an acquire, and that they may be NULL or invalid when the
       DirectBuffer is not acquired.

RETURN VALUE

       ggiDBGetNumBuffers returns the number  of  DirectBuffers  available.  0
       indicates that no DirectBuffers are available.

       ggiDBGetBuffer returns a pointer to a DirectBuffer structure.

TYPES OF BUFFERS

       Only the framebuffer is defined currently. Other types of buffers, such
       as stencil, z will be defined by appropriate GGI extensions.

       A frame buffer may be organized  as  several  distinct  buffers.   Each
       buffer  may  have  a  different  layout. This means both the addressing
       scheme to be used as well as the addressing parameters may differ  from
       buffer to buffer.

       A  framebuffer  is  denoted  by ggi_directbuffer.type==GGI_DB_NORMAL.
       Each frame  has  its  own  buffer,  and  its  number  is  indicated  in
       ggi_directbuffer.frame.

EXAMPLES

       How to obtain a DirectBuffer:

       ggi_visual_t  vis;
       ggi_mode      mode;
       int           i;

       /* Framebuffer info */
       unsigned char *fbptr[2];
       int stride[2];
       int numbufs;

       mode.frames = 2;      /* Double-buffering */
       mode.visible.x = 640; /* Screen res */
       mode.visible.y = 480;
       mode.virt.x = GGI_AUTO; /* Any virtual resolution.  Will usually be set */
       mode.virt.y = GGI_AUTO; /* to be the same as visible but some targets */
                               /* may have restrictions on virtual size. */
       mode.graphtype = GT_8BIT;             /* Depend on 8-bit palette. */
       mode.dpp.x = mode.dpp.y = GGI_AUTO;   /* Always 1x1 but we don’t care. */

       if(ggiInit()) {
             /* Failed to initialize library. Bomb out. */
       }

       vis = ggiOpen(NULL);
       if(!vis) {
             /* Opening default visual failed, quit. */
       }

       if(ggiSetMode(vis, &mode)) {
             /* Set mode has failed, should check if suggested mode
                is o.k. for us, and try the call again. */
       }

       numbufs = ggiDBGetNumBuffers(vis);

       for(i = 0; i < numbufs; i++) {
             ggi_directbuffer *db;
             int frameno;

             db = ggiDBGetBuffer(vis, i);

             if(!(db->type & GGI_DB_SIMPLE_PLB))
             {
                     /* We don’t handle anything but simple pixel-linear buffers.
                        Fall back to ggiPutBox() or something. */
                     continue;
             }

             frameno = db->frame;

             if(readptr[frameno] != NULL &&
                     (db->buffer.plb.pixelformat->flags & GGI_PF_REVERSE_ENDIAN))
             {
                     continue;
             }

             fbptr[frameno] = db->write;     /* read == write for simple plbs */

             /* Stride of framebuffer (in bytes). */
             stride[frameno] = db->buffer.plb.stride;

             /* Check pixel format, be portable... */

SEE ALSO

       ggi_directbuffer(3), ggiResourceAcquire(3)