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 Structures like 'GP_Context' are not created by the 'GP_ContextAlloc()'
   7 function but have proper constructor and destructor to keep the Python
   8 reference counting happy.
   9
  10 There there are more complicated problems like 'GP_ProgressCallback' which
  11 needs a proxy function to call the python callback from the C code.
  12
  13 Context
  14 ~~~~~~~
  15
  16 [source,python]
  17 -------------------------------------------------------------------------------
  18 import gfxprim.core as core
  19
  20     # Create 100x100 RGB888 context
  21     c = core.Context(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 context 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 May raise 'OSError' with 'ENOMEM' errno if allocation has failed.
  33
  34 [source,python]
  35 -------------------------------------------------------------------------------
  36 import gfxprim.core as core
  37
  38     pixel = context.GetPixel(x, y)
  39
  40 -------------------------------------------------------------------------------
  41
  42 Returns a pixel value at x and y. If coordinates are outside the image zero is
  43 returned.
  44
  45 [source,python]
  46 -------------------------------------------------------------------------------
  47 import gfxprim.core as core
  48
  49     context.PutPixel(x, y, pixel)
  50
  51 -------------------------------------------------------------------------------
  52
  53 Puts a pixel at specified coordinates. If coordinates are outside of the
  54 image nothing is done.
  55
  56 NOTE: You may want to see link:coordinate_system.html[coordinate system]
  57       description.
  58
  59 [source,python]
  60 -------------------------------------------------------------------------------
  61 import gfxprim.core as core
  62
  63     grayscale = context.Convert(core.C.PIXEL_G8)
  64
  65 -------------------------------------------------------------------------------
  66
  67 Returns context converted into the desired pixel format.
  68
  69 The conversion is naive i.e. the values are just divided/multiplied.
  70
  71 //TODO: link to dithering filters etc.
  72
  73 [source,python]
  74 -------------------------------------------------------------------------------
  75 import gfxprim.core as core
  76
  77     # Blits context to target starting at
  78     # sx and sy in the source context
  79     # tx and ty in in the target
  80     context.Blit(sx, sy, target, tx, ty, w, h)
  81
  82     # Alternatively the size can be described by
  83     # coordinates in the source or target
  84     context.Blit(sx, sy, target, tx, ty, sx2=, sy2=)
  85     context.Blit(sx, sy, target, tx, ty, tx2=, ty2=)
  86
  87 -------------------------------------------------------------------------------
  88
  89 Copy a rectangle from self to target.
  90
  91 The blits can do simple conversions same as the 'Convert' functions however
  92 such blits are slower.
  93
  94 Blit is clipped.
  95
  96 TIP: See link:example_py_showimage.html[example] Blit usage.
  97
  98 [[Colors_and_Pixels]]
  99 Colors and Pixels
 100 ~~~~~~~~~~~~~~~~~
 101
 102 Pixel in gfxprim is a number large enough to store a pixel value. Pixel is
 103 passed as a parameter to all drawing functions.
 104
 105 Color is a more abstract representation for example RGB triplet.
 106
 107 There are several functions to create a pixel value for a particular pixel
 108 type from color.
 109
 110 [source,python]
 111 -------------------------------------------------------------------------------
 112 import gfxprim.core as core
 113
 114     # You can create a pixel from RGB and pixel type
 115     black = core.RGBToPixel(0, 0, 0, core.C.PIXEL_G1)
 116
 117     # Or using shortcut from context
 118     black = context.RGBToPixel(0, 0, 0)
 119
 120 -------------------------------------------------------------------------------
 121
 122 These functions creates a pixel suitable for drawing into a bitmap with
 123 particular pixel type.
 124
 125
 126 [source,python]
 127 -------------------------------------------------------------------------------
 128 import gfxprim.core as core
 129
 130     # Print all supported pixel types
 131     for i in core.PixelTypes:
 132             print("Pixel type '{}' size {}".format(i.name, i.size))
 133
 134 -------------------------------------------------------------------------------
 135
 136 The PixelTypes array stores all supported pixel types
 137
 138 Debug Functions
 139 ~~~~~~~~~~~~~~~
 140
 141 [source,python]
 142 -------------------------------------------------------------------------------
 143 import gfxprim.core as core
 144
 145     core.GP_SetDebugLevel(10)
 146
 147     level = core.GP_GetDebugLevel()
 148 -------------------------------------------------------------------------------
 149
 150 Sets and gets the GFXprim debug level. See link:debug.html[debug messages]
 151 description for more details.
 152
 153
 154
 155
 156 These are basic 'Context' methods from core module. Importing other modules
 157 will add some other (for example gfx module adds all drawing functions).