Python Core module
------------------

The python binding maps mostly to the C API with the 'gp_' prefix stripped.

However structures as 'gp_pixmap' are not created by the 'gp_pixmap_alloc()'
function but have proper constructor and destructor to keep the Python
reference counting happy.

Then there are a bit more tricky solutions, such as 'gp_progress_cb'
which needs a proxy function to call the python callback from the C code.

Pixmap
~~~~~~~

[source,python]
-------------------------------------------------------------------------------
import gfxprim.core as core

    # Create 100x100 RGB888 pixmap
    c = core.pixmap(100, 100, core.C.PIXEL_RGB888)

    print("w={} h={} bpp={}".format(c.w, c.h, c.bpp))

-------------------------------------------------------------------------------

Creates a pixmap of a particular size and pixel type.

First two parameters are 'width' and 'height' third is pixel type which is an
enumeration

|===============================================================================
| May raise 'OSError' with errno set to 'ENOMEM' if allocation has failed.

| May raise 'OSError' with errno set to 'EINVAL' for invalid pixel type and/or
  zero width or height.

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

[source,python]
-------------------------------------------------------------------------------
import gfxprim.core as core

    pixel = pixmap.get_pixel(x, y)

-------------------------------------------------------------------------------

Returns a pixel value at x and y. If coordinates are outside the image zero is
returned.

[source,python]
-------------------------------------------------------------------------------
import gfxprim.core as core

    pixmap.put_pixel(x, y, pixel)

-------------------------------------------------------------------------------

Puts a pixel at specified coordinates. If coordinates are outside of the
image nothing is done.

NOTE: You may want to see link:coordinate_system.html[coordinate system]
      description.

[source,python]
-------------------------------------------------------------------------------
import gfxprim.core as core

    grayscale = pixmap.convert(core.C.PIXEL_G8)

-------------------------------------------------------------------------------

Returns pixmap converted into the desired pixel format.

The conversion is naive i.e. the values are just divided/multiplied.

//TODO: link to dithering filters etc.

[source,python]
-------------------------------------------------------------------------------
import gfxprim.core as core

    # Blits pixmap to target starting at
    # sx and sy in the source pixmap
    # tx and ty in in the target
    pixmap.blit(sx, sy, target, tx, ty, w, h)

    # Alternatively the size can be described by
    # coordinates in the source or target
    pixmap.blit(sx, sy, target, tx, ty, sx2=, sy2=)
    pixmap.blit(sx, sy, target, tx, ty, tx2=, ty2=)

-------------------------------------------------------------------------------

Copy a rectangle from self to target.

The blits can do naive conversions (same as 'convert') however such blits are
a bit slower.

Blit is clipped.

TIP: See link:example_py_showimage.html[example Blit usage].

[[Pixels]]
Pixels
~~~~~~

Pixel in GFXprim is a number large enough to store a pixel value. Pixel is
passed as a parameter to all drawing functions.

There are several functions to create a pixel value for a particular pixel
type from color.

[source,python]
-------------------------------------------------------------------------------
import gfxprim.core as core

    # You can create a pixel from RGB and pixel type
    black = core.rgb_to_pixel(0, 0, 0, core.C.PIXEL_G1)

    # Or using shortcut from pixmap
    black = pixmap.rgb_to_pixel(0, 0, 0)

-------------------------------------------------------------------------------

These functions creates a pixel suitable for drawing into a bitmap with
particular pixel type.

[source,python]
-------------------------------------------------------------------------------
import gfxprim.core as core

    # Print all supported pixel types
    for i in core.pixel_types:
            print("Pixel type '{}' size {}".format(i.name, i.size))

-------------------------------------------------------------------------------

The pixel_types array stores all supported pixel types

[[Progress_Callback]]
Progress Callback
~~~~~~~~~~~~~~~~~

Progress callback is the last parameter of link:loaders_python.html[loaders]
and link:filters_python.html[filters]. It can be either a python function or a
touple with a function at first position. In the latter case the second touple
element is passed to the callback function as a second parameter. First
parameter of the callback is a floating point number with the current progress
in percents.

Progress callback must return an integer number. Returning non-zero will abort
the operation and the function, called with the callback as a parameter, will
return 'OSError' with errno set to 'ECANCELED'.

TIP: See link:example_py_progress_callback.html[callback example].

Debug Functions
~~~~~~~~~~~~~~~

[source,python]
-------------------------------------------------------------------------------
import gfxprim.core as core

    core.set_debug_level(10)

    level = core.get_debug_level()
-------------------------------------------------------------------------------

Sets and gets the GFXprim debug level. See link:debug.html[debug messages]
description for more details.

These are basic 'Pixmap' methods from core module. Importing other modules
will add some other (for example gfx module adds all drawing functions).
