filters/gp_filter_resize_alloc: Check w and h
[gfxprim.git] / doc / core_python.txt
blob24295d84a63c6d5257b0cb9e028c258779770ce9
1 Python Core module
2 ------------------
4 The python binding maps mostly to the C API with the 'gp_' prefix stripped.
6 However structures as 'gp_pixmap' are not created by the 'gp_pixmap_alloc()'
7 function but have proper constructor and destructor to keep the Python
8 reference counting happy.
10 Then there are a bit more tricky solutions, such as 'gp_progress_cb'
11 which needs a proxy function to call the python callback from the C code.
13 Pixmap
14 ~~~~~~~
16 [source,python]
17 -------------------------------------------------------------------------------
18 import gfxprim.core as core
20     # Create 100x100 RGB888 pixmap
21     c = core.pixmap(100, 100, core.C.PIXEL_RGB888)
23     print("w={} h={} bpp={}".format(c.w, c.h, c.bpp))
25 -------------------------------------------------------------------------------
27 Creates a pixmap of a particular size and pixel type.
29 First two parameters are 'width' and 'height' third is pixel type which is an
30 enumeration
32 |===============================================================================
33 | May raise 'OSError' with errno set to 'ENOMEM' if allocation has failed.
35 | May raise 'OSError' with errno set to 'EINVAL' for invalid pixel type and/or
36   zero width or height.
38 |===============================================================================
40 [source,python]
41 -------------------------------------------------------------------------------
42 import gfxprim.core as core
44     pixel = pixmap.get_pixel(x, y)
46 -------------------------------------------------------------------------------
48 Returns a pixel value at x and y. If coordinates are outside the image zero is
49 returned.
51 [source,python]
52 -------------------------------------------------------------------------------
53 import gfxprim.core as core
55     pixmap.put_pixel(x, y, pixel)
57 -------------------------------------------------------------------------------
59 Puts a pixel at specified coordinates. If coordinates are outside of the
60 image nothing is done.
62 NOTE: You may want to see link:coordinate_system.html[coordinate system]
63       description.
65 [source,python]
66 -------------------------------------------------------------------------------
67 import gfxprim.core as core
69     grayscale = pixmap.convert(core.C.PIXEL_G8)
71 -------------------------------------------------------------------------------
73 Returns pixmap converted into the desired pixel format.
75 The conversion is naive i.e. the values are just divided/multiplied.
77 //TODO: link to dithering filters etc.
79 [source,python]
80 -------------------------------------------------------------------------------
81 import gfxprim.core as core
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)
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=)
93 -------------------------------------------------------------------------------
95 Copy a rectangle from self to target.
97 The blits can do naive conversions (same as 'convert') however such blits are
98 a bit slower.
100 Blit is clipped.
102 TIP: See link:example_py_showimage.html[example Blit usage].
104 [[Pixels]]
105 Pixels
106 ~~~~~~
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.
111 There are several functions to create a pixel value for a particular pixel
112 type from color.
114 [source,python]
115 -------------------------------------------------------------------------------
116 import gfxprim.core as core
118     # You can create a pixel from RGB and pixel type
119     black = core.rgb_to_pixel(0, 0, 0, core.C.PIXEL_G1)
121     # Or using shortcut from pixmap
122     black = pixmap.rgb_to_pixel(0, 0, 0)
124 -------------------------------------------------------------------------------
126 These functions creates a pixel suitable for drawing into a bitmap with
127 particular pixel type.
129 [source,python]
130 -------------------------------------------------------------------------------
131 import gfxprim.core as core
133     # Print all supported pixel types
134     for i in core.pixel_types:
135             print("Pixel type '{}' size {}".format(i.name, i.size))
137 -------------------------------------------------------------------------------
139 The pixel_types array stores all supported pixel types
141 [[Progress_Callback]]
142 Progress Callback
143 ~~~~~~~~~~~~~~~~~
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.
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'.
156 TIP: See link:example_py_progress_callback.html[callback example].
158 Debug Functions
159 ~~~~~~~~~~~~~~~
161 [source,python]
162 -------------------------------------------------------------------------------
163 import gfxprim.core as core
165     core.set_debug_level(10)
167     level = core.get_debug_level()
168 -------------------------------------------------------------------------------
170 Sets and gets the GFXprim debug level. See link:debug.html[debug messages]
171 description for more details.
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).