===================
LibGGIBlt Reference
===================


.. include:: libggiblt-functions.txt

.. include:: libggiblt-structures.txt


LibGGIBlt libraries and targets
===============================


An extension to LibGGI blitting operations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. manpage:: 7 libggiblt

Description
-----------

LibGGIBlt is an extension to LibGGI which adds functionality
pertaining to blitting and management of blit data sources.  LibGGI is
a graphics library developed by the GGI Project
(http://www.ggi-project.org/).


Blitting is the process of copying patterns and textures to a
framebuffer, usually as a rectangle, trapezoid, or triangle, and
applying a mathemetical or logical transformation on the data as it is
being transferred.  Many of these transforms enjoy widespread support
in even not-so-modern video hardware, and many other APIs have offered
functional interfaces to these operations.  Forget what you know about
those.  The future is now.  LibGGIBlt is likely NOT like any other
previously developed interface to blitting operations you have seen.


In order to makes sense of LibGGIBlt's API, envision a spreadsheet.
Along the top of the columns is a header for each column, designating
the various parameters that you would normally send through a blitting
library's functional interface, for example, x,y start point, widths
and heights, clipping rectangles, colors, linear addresses of
patterns, etc. etc. etc.  Each column represents one of those
parameters, and each row represents an invocation of a blitting
operation.  Once you have that picture painted in your head,
LibGGIBlt's API will be easier to learn -- and to leverage.


LibGGIBlt's API helps you manage such a spreadsheet of graphics
commands: altering rows and columns, and sending ranges of rows to the
target for rendering.  Since LibBlt actually keeps the rows you place
into the *spreadsheet* in a form precompiled specially for the target,
this can resuly in some very fast batch drawing operations.  LibGGIBlt
also provides a fallback mechanism which provides emulation on all
supported LibGGI visuals, and a functionally oriented interface for
those not feeling up for a paradigm shift.


Environment variables
---------------------

The following outlines the environment variables, intended for the user,
which affect the behaviour of LibGGIBlt:

`BLT_DEBUG`
	The debugging level for LibBlt:

	- ``0`` or unset : debug output is off; debugging is off
	- ``255`` : all debug output is on

	You may also bitwise-or any of the following together:
	
	- 2 : debug core
	- 4 : debug mode setting
	- 8 : debug color handling
	- 16 : debug drawing
	- 32 : misc debugging output
	- 64 : debug dynamic library handling

	The debugging output can be quite verbose and in most cases
	you should redirect stderr so that it does not interfere with
	your program's output.

`BLT_DEBUGSYNC`
	Turn on synchronous debugging output, flushing the output
	buffers before returning from `GGIDPRINT` calls.
