doc/core_python.txt

   1 Python Core module
   2 ------------------
   3
   4 The python binding maps mostly to the C API with the 'GP_' prefix stripped.
   5
   6 However structures as 'GP_Pixmap' are not created by the 'GP_PixmapAlloc()'
   7 function but have proper constructor and destructor to keep the Python
   8 reference counting happy.
   9
  10 Then there are a bit more tricky solutions, such as 'GP_ProgressCallback'
  11 which needs a proxy function to call the python callback from the C code.
  12
  13 Pixmap
  14 ~~~~~~~
  15
  16 [source,python]
  17 -------------------------------------------------------------------------------
  18 import gfxprim.core as core
  19
  20     # Create 100x100 RGB888 pixmap
  21     c = core.Pixmap(100, 100, core.C.PIXEL_RGB888)
  22
  23     print("w={} h={} bpp={}".format(c.w, c.h, c.bpp))
  24
  25 -------------------------------------------------------------------------------
  26
  27 Creates a pixmap of a particular size and pixel type.
  28
  29 First two parameters are 'width' and 'height' third is pixel type which is an
  30 enumeration
  31
  32 |===============================================================================
  33 | May raise 'OSError' with errno set to 'ENOMEM' if allocation has failed.
  34
  35 | May raise 'OSError' with errno set to 'EINVAL' for invalid pixel type and/or
  36   zero width or height.
  37
  38 |===============================================================================
  39
  40 [source,python]
  41 -------------------------------------------------------------------------------
  42 import gfxprim.core as core
  43
  44     pixel = pixmap.GetPixel(x, y)
  45
  46 -------------------------------------------------------------------------------
  47
  48 Returns a pixel value at x and y. If coordinates are outside the image zero is
  49 returned.
  50
  51 [source,python]
  52 -------------------------------------------------------------------------------
  53 import gfxprim.core as core
  54
  55     pixmap.PutPixel(x, y, pixel)
  56
  57 -------------------------------------------------------------------------------
  58
  59 Puts a pixel at specified coordinates. If coordinates are outside of the
  60 image nothing is done.
  61
  62 NOTE: You may want to see link:coordinate_system.html[coordinate system]
  63       description.
  64
  65 [source,python]
  66 -------------------------------------------------------------------------------
  67 import gfxprim.core as core
  68
  69     grayscale = pixmap.Convert(core.C.PIXEL_G8)
  70
  71 -------------------------------------------------------------------------------
  72
  73 Returns pixmap converted into the desired pixel format.
  74
  75 The conversion is naive i.e. the values are just divided/multiplied.
  76
  77 //TODO: link to dithering filters etc.
  78
  79 [source,python]
  80 -------------------------------------------------------------------------------
  81 import gfxprim.core as core
  82
  83     # Blits pixmap to target starting at
  84     # sx and sy in the source pixmap
  85     # tx and ty in in the target
  86     pixmap.Blit(sx, sy, target, tx, ty, w, h)
  87
  88     # Alternatively the size can be described by
  89     # coordinates in the source or target
  90     pixmap.Blit(sx, sy, target, tx, ty, sx2=, sy2=)
  91     pixmap.Blit(sx, sy, target, tx, ty, tx2=, ty2=)
  92
  93 -------------------------------------------------------------------------------
  94
  95 Copy a rectangle from self to target.
  96
  97 The blits can do naive conversions (same as 'Convert') however such blits are
  98 a bit slower.
  99
 100 Blit is clipped.
 101
 102 TIP: See link:example_py_showimage.html[example Blit usage].
 103
 104 [[Pixels]]
 105 Pixels
 106 ~~~~~~
 107
 108 Pixel in GFXprim is a number large enough to store a pixel value. Pixel is
 109 passed as a parameter to all drawing functions.
 110
 111 There are several functions to create a pixel value for a particular pixel
 112 type from color.
 113
 114 [source,python]
 115 -------------------------------------------------------------------------------
 116 import gfxprim.core as core
 117
 118     # You can create a pixel from RGB and pixel type
 119     black = core.RGBToPixel(0, 0, 0, core.C.PIXEL_G1)
 120
 121     # Or using shortcut from pixmap
 122     black = pixmap.RGBToPixel(0, 0, 0)
 123
 124 -------------------------------------------------------------------------------
 125
 126 These functions creates a pixel suitable for drawing into a bitmap with
 127 particular pixel type.
 128
 129 [source,python]
 130 -------------------------------------------------------------------------------
 131 import gfxprim.core as core
 132
 133     # Print all supported pixel types
 134     for i in core.PixelTypes:
 135             print("Pixel type '{}' size {}".format(i.name, i.size))
 136
 137 -------------------------------------------------------------------------------
 138
 139 The PixelTypes array stores all supported pixel types
 140
 141 [[Progress_Callback]]
 142 Progress Callback
 143 ~~~~~~~~~~~~~~~~~
 144
 145 Progress callback is the last parameter of link:loaders_python.html[loaders]
 146 and link:filters_python.html[filters]. It can be either a python function or a
 147 touple with a function at first position. In the latter case the second touple
 148 element is passed to the callback function as a second parameter. First
 149 parameter of the callback is a floating point number with the current progress
 150 in percents.
 151
 152 Progress callback must return an integer number. Returning non-zero will abort
 153 the operation and the function, called with the callback as a parameter, will
 154 return 'OSError' with errno set to 'ECANCELED'.
 155
 156 TIP: See link:example_py_progress_callback.html[callback example].
 157
 158 Debug Functions
 159 ~~~~~~~~~~~~~~~
 160
 161 [source,python]
 162 -------------------------------------------------------------------------------
 163 import gfxprim.core as core
 164
 165     core.SetDebugLevel(10)
 166
 167     level = core.GetDebugLevel()
 168 -------------------------------------------------------------------------------
 169
 170 Sets and gets the GFXprim debug level. See link:debug.html[debug messages]
 171 description for more details.
 172
 173 These are basic 'Pixmap' methods from core module. Importing other modules
 174 will add some other (for example gfx module adds all drawing functions).