Accessing the Buffer

Read and write access to the buffer is done using load and store instructions of the host CPU. The access width and alignment requirements are specified in the ggi_directbuffer structure.

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.

More importantly, certain DirectBuffers need to be explicitly acquired (i.e. locked) before using (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. An acquire is done by using ggiResourceAcquire(3) and it is released by calling ggiResourceRelease(3) You can determine whether the DirectBuffer needs to be acquired by using ggiResourceMustAcquire(3)

Be aware 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.

Paged Buffers

Paged buffers are indicated with page_size != 0 in ggi_directbuffer.

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.