General information
-------------------

GFXprim is simple modular 2D bitmap graphics library with emphasis on
speed and correctness. It comes batteries included, but free from
bloat.

It includes:

* Graphical user interface widgets with object hierarchy and
  declarative layouts.
* Clean and non-intrusive implementations of elementary data
  structures.
* Multiple rendering backends supporting desktop to embedded.
* Integrations with many image loaders.
* Image filters
* Sample applications including image and PDF viewers.
* Many tests

One of the key points of the library are code generators. Most of the
graphics operations are written using https://github.com/metan-ucw/cct[CCT]
templating engine which is used to create specialized C code. So,
for an example, once you add pixel definition into configuration file,
creating specialized filters, loaders and conversions to other pixel
formats is just a matter of typing +make rebuild+.

Core
----

The Core of the library contains a minimal amount of code to define
interfaces that are shared between all parts of the library.

The most important part of the core is the link:pixmap.html[gp_pixmap]
structure that represents an in-memory pixmap.

The Core also contains generated code for basic operations such as
link:get_put_pixel.html[gp_get_pixel], link:get_put_pixel.html[gp_put_pixel]
and optimized functions for writing continous lines of pixels 'gp_write_pixels'
that are a base for the more complex drawing primitives in GFX or for the
graphics operations in Filters.

link:blits.html[Blits] are functions used to copy part of one bitmap into
another bitmap. The blits be also used for primitive bitmap pixel type
conversions (i.e. RGB888 vs BGR888).

link:progress_callback.html[Progress Callback] is an interface that
allows you to monitor progress of an operation. It is mainly used in
loaders and filters. Generally, any operation that is not very quick
takes an optional pointer to a progress-callback that allows your
program to monitor and possibly abort the operation.

The link:debug.html[Debug] interface is used as a unified facility to
print debug messages, control debug level, etc.

There is also support for link:gamma.html[Gamma] correction. Unfortunatelly
not all parts of library use it at the moment.

And last but not least: Core is a home for some link:core.html[common macros]
that are used from different parts of the library.

Gfx
---

link:gfx.html[Gfx] is part of the library that implements basic
graphics primitives such as lines, circles, polygons, etc. Classical
primitives are nearly finished. Work on anti-aliased primitives has been
started.

Text
----

The link:text.html[Text] part of the library implements basic support
for printing text into a bitmap. There are two bitmap fonts compiled
directly into the library and we support True Type fonts through
link:http://freetype.org[FreeType] (so far ASCII printable characters
only).

[[Loaders]]
Loaders
-------

link:loaders.html[Loaders] are the part that is resposible for loading
and saving images into various standard formats (PNG, JPEG, GIF, TIFF,
BMP, PNM, etc...).

.Currently supported formats
[width="100%",options="header"]
|=============================================================================
| Extension | Format Name | Read Support | Write Support

| JPEG | | [green]*Yes* | [green]*Yes*

| PNG |
  Portable Network Graphics |
  [green]#16 Bit RGB not supported# |
  [green]#16 Bit RGB not supported#

| GIF |
  Graphics Interchange Format |
  [green]*Yes* |
  [black]*No*

| BMP | |
  [green]#RLE4 and some less common bitfiels not supported# |
  [green]#RGB888 only#

| TIFF |
  Tagged Image File Format |
  [green]#Most of the Palette, RGB and Grayscale works (no tiles yet)# |
  [green]#RGB888 and Grayscale#

| WEBP ||
  [green]*Yes* |
  [black]*No*

| PSP |
  Paint Shop Pro Image |
  [green]#Composite image only for newer formats than 3.0# |
  [black]*No*

| PSD |
  Adobe Photoshop Image |
  [green]#Thumbnail or Merged image (16 bit RGB and CMYK not supported yet)#|
  [black]*No*

| PBM PGM PPM PNM |
  Netpbm portable bitmap |
  [green]#All but < 8bit binary grayscale# |
  [green]#All ASCII formats#

| JP2 |
  JPEG 2000 |
  [green]#Experimental support for RGB images# |
  [black]*No*

| PCX |
  ZSoft PCX |
  [green]*Yes* |
  [black]*No*

| CBZ |
  Comic book archive |
  [green]#Experimental support via ZIP Container# |
  [black]*No*

|=============================================================================


Filters
-------

link:filters.html[Filters] are the part of the library that implements
bitmap image filters.

.Currently Implemented Point Filters
[width="100%",options="header"]
|=============================================================================
| Filter Name | Supported Pixel Type | Multithreaded
| Brightness  | All                  | Not Applicable
| Contrast    | All                  | Not Applicable
| Invert      | All                  | Not Applicable
| Posterize   | All                  | Not Applicable
|=============================================================================

.Currently Implemented Linear Filters
[width="100%",options="header"]
|=============================================================================
| Filter Name            | Supported Pixel Type | Mutithreaded
| Convolution            | All                  | Yes
| Separable Convolution  | All                  | Yes
| Gaussian Blur          | All                  | Yes
| Sobel Edge Detection   | RGB888               | Yes
| Prewitt Edge Detection | RGB888               | Yes
|=============================================================================

.Currently Implemented Aritmetic Filters
[width="100%",options="header"]
|=============================================================================
| Filter Name | Supported Pixel Type | Multithreaded
| Addition    | All                  | No
| Multiplication | All               | No
| Difference  | All                  | No
| Max, Min    | All                  | No
|=============================================================================

.Currently Implemented Ditherings
[width="100%",options="header"]
|=============================================================================
| Filter Name     | Supported Pixel Type | Multithreaded
| Floyd Steinberg | All -> Any           | No
| Hilbert Peano   | All -> Any           | No
|=============================================================================

.Currently Implemented Resamplings
[width="100%",options="header"]
|=============================================================================
| Filter Name                    | Supported Pixel Type | Multithreaded
| Nearest Neighbour              | All                  | No
| Bilinear (Integer Arithmetics) | All                  | No
| Bicubic (Integer Arithmetics)  | All                  | No
| Bicubic (Float Arithmetics)    | RGB888               | No
|=============================================================================

.Rotation and mirroring
[width="100%",options="header"]
|=============================================================================
| Filter Name         | Supported Pixel Type | Multithreaded
| Rotate 90           | All                  | No
| Rotate 180          | All                  | No
| Rotate 270          | All                  | No
| Mirror Vertically   | All                  | No
| Mirror Horizontally | All                  | No
|=============================================================================

.Misc filters
[width="100%",options="header"]
|=============================================================================
| Filter Name             | Supported Pixel Type | Multithreaded
| Histogram               | All                  | No
| Additive Gaussian Noise | All                  | No
| Median                  | RGB888               | No
| Weighted Median         | RGB888               | No
| Sigma Lee               | RGB888               | No
|=============================================================================

Backends
--------

link:backends.html[Backends] together with link:input.html[Input] form
an API for drawing on screen (or into a window) and for getting
keystrokes/mouse coordinates. So far we support X11, the Linux
framebuffer, SDL and AALib as graphics backends.

There is also a virtual backend used for testing. This allows you to
create a backend of any pixel type on the top of other backends.

Python bindings
---------------

Python bindings currently cover most of the library, there is (work in
progress) documentation for link:core_python.html[Core],
link:gfx_python.html[Gfx], link:loaders_python.html[Loaders],
link:filters_python.html[Filters] and link:backends_python.html[Backends].

Work in progress
----------------

* Anti Aliased drawing

* Gamma correction and color profiles
