Chapter 11. DirectBuffer

Table of Contents
Types of Buffers
Accessing the Buffer
DirectBuffer Structures
Getting DirectBuffers

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.

Types of Buffers

Only the framebuffer is defined currently.

Framebuffer

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.

LibGGI currently has support for pixel-linear buffers, bit-planar buffers, and interleaved planar buffers.

Pixel Linear Buffer

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, x must be less than size_x and y must be less than size_y. 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 bpp 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.