Methods for raw access to buffer data
Name
ggiBufClearBuffer, ggiBufBuf2Mem, ggiBufMem2Buf, ggiBufBuf2Buf, ggiBufConst2Buf, ggiBufGetValue, ggiBufPutValue : Methods for raw access to buffer data
Synopsis
#include <ggi/buf.h> int ggiBufClearBuffer(ggiBuf_t buf); int ggiBufBuf2Mem(ggiBuf_t src, size_t xoffset, size_t yoffset, size_t stride, void *membuf, size_t deststride, size_t linewidth, size_t numlines); int ggiBufMem2Buf(ggiBuf_t dest, size_t xoffset, size_t yoffset, size_t stride, void *membuf, size_t srcstride, size_t linewidth, size_t numlines); int ggiBufBuf2Buf(ggiBuf_t dest, size_t xoffset, size_t yoffset, size_t stride, ggiBuf_t src, size_t srcxoffset, size_t srcyoffset, size_t srcstride, size_t linewidth, size_t numlines); int ggiBufConst2Buf(ggiBuf_t dest, size_t xoffset, size_t yoffset, size_t stride, ggi_bufval val, size_t linewidth, size_t numlines); int ggiBufGetValue(ggiBuf_t buf, size_t xoffset, size_t yoffset, size_t stride, ggi_bufval *val); int ggiBufPutValue(ggiBuf_t buf, size_t xoffset, size_t yoffset, size_t stride, ggi_bufval val);
Description
ggiBufPutValue and ggiBufGetValue set or retrieve a single value from the data inside a buffer. The value is taken from or stored in the parameter named val, respectively.
ggiBufConst2Buf fills data locations inside the buffer with the constant value given in the parameter mem. ggiBufClear fills the entire buffer with the default background value of the buffer.
ggiBufMem2Buf and ggiBufBuf2Mem set or retrieve values from the data inside the buffer. The values are taken from or stored to the memory area pointed to by the parameter named membuf. After each line of data is transferred, memstride bytes are skipped in the memory area.
ggiBuf2Buf moves values from one buffer to another.
In all functions, the parameter src, if present, designates the buffer from which to take data and the parameter dest, if present, designates the buffer into which to store data.
In all functions, the parameter stride (and srcstride, if present) represent the number of values between two consecutive lines of the buffer. However, if the value 0 is given, the default stride stored in the ggiBuf_t is used.
In all functions, the xoffset, yoffset parameters (and srcxoffset, srcyoffset, if present) give the number of values from the start of the buffer to skip before beginning to access the data. The first data item accessed is the value at offset yoffset * stride + xoffset (or srcyoffset * srcstride + srcyoffset).
Return value
The functions return zero or a positive value on success, or a negative value on failure. The positive value will contain bitflags: 'BUF_ACCESSFUNC_UNNEEDED', designates that there is no special access method or non-trivial data layout involved in accessing the data inside the buffer, and as such the user may proceed to access the contents of the buffer directly through the pointers provided in the object as if it were normal system RAM, provided ggiFlush(3) has been called to clear any pending drawing functions which may also be accessing the data. The positive value 'BUF_ACCESSFUNC_NOFLUSH' means that it is not necessary to call ggiFlush(3) before accessing the data.
Helper macros
The following macros can be used if the buffer is 1D:
#define ggiBufBuf2Mem1D(src, offset, dest, linewidth) \ ggiBufBuf2Mem(src, offset, 0, 0, dest, 0, linewidth, 0); #define ggiBufMem2Buf1D(dest, offset, membuf, linewidth) \ ggiBufMem2Buf(dest, offset, 0, 0, membuf, 0, linewidth, 0); #define ggiBufBuf2Buf1D(dest, offset, src, srcoffset, srcstride, linewidth) \ ggiBufBuf2Buf(dest, offset, 0, 0, src, srcoffset, 0, \ 0, srcstride, linewidth, 0); #define ggiBufConst2Buf1D(dest, offset, val, linewidth) \ ggiBufConst2Buf(dest, offset, 0, 0, val, linewidth, 0); #define ggiBufGetValue1D(buf, offset, val) \ ggiBufGetValue(buf, offset, 0, 0, val); #define ggiBufPutValue1D(buf, offset, val) \ ggiBufPutValue(buf, offset, 0, 0, val);