This is an automated email from the git hooks/post-receive script. It was generated because a ref change was pushed to the repository containing the project gfxprim.git. The branch, master has been updated via 5b9a67f154c6251afb1203702830b837297a1030 (commit) via 282b616826f4ad7cfd9c3b804c649e61e56a9b32 (commit) via f63f5aa939d96a4abb0b345470dd7d92ab65a360 (commit) from 2600399e7b0b62f90f89278758e619402535d74d (commit) Those revisions listed above that are new to this repository have not appeared on any other notification email; so we list those revisions in full, below. - Log ----------------------------------------------------------------- http://repo.or.cz/w/gfxprim.git/commit/5b9a67f154c6251afb1203702830b837297a1... commit 5b9a67f154c6251afb1203702830b837297a1030 Author: Cyril Hrubis <metan@ucw.cz> Date: Sun Dec 1 20:28:53 2013 +0100 doc: Add C core documentation page + cleanup. Signed-off-by: Cyril Hrubis <metan@ucw.cz> diff --git a/doc/Makefile b/doc/Makefile index 197e81d..28cc670 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -4,7 +4,7 @@ SOURCES=index.html about.txt context.txt loaders.txt filters.txt gen.txt pixels.txt coordinate_system.txt coding_style.txt get_put_pixel.txt blits.txt progress_callback.txt text.txt event_queue.txt compilation.txt filters_resize.txt - filters_dithering.txt filters_python.txt spiv.txt + filters_dithering.txt filters_python.txt spiv.txt core_common.txt SOURCES+=core_python.txt gfx_python.txt loaders_python.txt backends_python.txt diff --git a/doc/asciidoc.conf b/doc/asciidoc.conf index 240991d..be8e2dd 100644 --- a/doc/asciidoc.conf +++ b/doc/asciidoc.conf @@ -49,6 +49,7 @@ ifdef::toc2[<link rel="stylesheet" href="{stylesdir=.}/toc2.css" type="text/css" </ul> C API Pages <ul> + <li><a href="core.html">Core</a></li> <li><a href="gfx.html">Gfx</a></li> <li><a href="text.html">Text</a></li> <li><a href="filters.html">Filters</a></li> diff --git a/doc/context.txt b/doc/context.txt index ea7d5ba..0d42abd 100644 --- a/doc/context.txt +++ b/doc/context.txt @@ -1,8 +1,8 @@ Drawing Context --------------- -The 'GP_Context' structure describes an 'in memory' pixmap. It contains all -metadata needed for drawing and filters. +The 'GP_Context' structure describes an 'in memory' pixmap. The structure +contains all metadata needed for drawing, loaders and filters. Data Structure ~~~~~~~~~~~~~~ @@ -40,14 +40,26 @@ typedef struct GP_Context { The 'pixels' field points to the image data. The 'pixels' are stored as a one-dimensional array consisting of byte-aligned -lines (i.e. each image line starts at whole byte and ends at whole byte). The -'pixels' array starts exactly at the start of the first line. Each line is -'bytes_per_row' bytes long. The first pixel may actually start at 'offset' bit -in the first byte in each line (but only for some sub contexts for pixel types -that are not byte aligned). The first pixel is followed by the rest of the -pixels in the image line (there is 'w' pixels in each line) and ends somewhere -before the end of the line (i.e. there may be padding before the start of the -next line or in case of subcontexts image data of the parent context). +lines (i.e. each image line starts at whole byte and ends at whole byte). + +The 'pixels' array starts exactly at upper left corner of the image and is +stored in horizontal lines (each line contains 'w' pixels and there is 'h' +lines). Each line is 'bytes_per_row' bytes long (which equals to 'w' * 'bpp' / +8 rouned up to the whole bytes). The first pixel may actually start at +'offset' bit in the first byte in each line (but only for some +<<Sub_Context,subcontexts>> for pixel types that are not byte aligned). + +The link:pixels.html[pixel_type enumeration] defines in which format and how +are pixel data stored in the 'pixels' buffer, i.e. organization and function +of the pixel channels. + +The optional pointer to link:gamma.html[gamma tables] describes per-channel +gamma correction. Unfortunatelly very few parts of the library use it at the +moment (this will be fixed in subsequent releases). + +The bitfield at the the end of the structure describes image orientation (see +bellow) and a flag that tell if 'pixels' data should be freed, which is +usefull for example for <<Sub_Context, subcontexts>>. Rotation ^^^^^^^^ @@ -213,6 +225,7 @@ If 'free_pixels' flag is set, the pixels buffer is freed too. If gamma pointer is not 'NULL' the 'GP_GammaRelease()' is called. +[[Sub_Context]] Subcontext ~~~~~~~~~~ diff --git a/doc/core.txt b/doc/core.txt index c7148fa..1ae253a 100644 --- a/doc/core.txt +++ b/doc/core.txt @@ -1,146 +1,49 @@ -Common code in Core -------------------- +Library Core +------------ -NOTE: Some of the interfaces described here (most notably the allocator) are - semi-internal interfaces and as such API is not considered stable. +Library core contains all basic data structures and functions that forms the +glue which holds the GFXprim libraries together. -Common Macros and Inline Functions -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The most important data structure is a link:context.html[Context] which +describes in-memory pixmap which is used extensively in all parts of the +library. -[source,c] -------------------------------------------------------------------------------- -#include <core/GP_Common.h> -/* or */ -#include <GP.h> +Core also contains link:gen.html[generated] code for basic pixel manipulations +such as link:get_put_pixel.html[GetPixel and PutPixel] as well as +link:blits.html[Blits] implementation. -GP_MIN(a, b); +Library Core is a place to implement common functinonality that is used from +the rest of the GFXprim modules, for example the link:debug.html[Debug layer] +or link:progress_callback.html[Progress callback]. -GP_MAX(a, b); +.Main Core library parts +[grid="rows"] +[options="autowidth"] +|============================================================================= +| link:context.html[Context] | Describes in-memory pixmap -GP_MAX3(a, b, c); +| link:basic_types.html[Basic types] | Types for size, lenght, pixel and + color -GP_ABS(a); +| link:pixels.html[Pixel types] | Pixel types handling and interface -GP_SWAP(a, b); +| link:get_put_pixel.html[GetPixel and PutPixel] | Macros and functions to + get and put pixels -GP_SIGN(a); +| link:blits.html[Blits] | Blits (copies) a rectangular area from one context to + another as well as simple pixel format conversions -GP_ARRAY_SIZE(arr); +| link:progress_callback.html[Progress Callback] | Progress callback passed + to all + link:filters.html[filters] + and + link:loaders.html[loaders] -GP_CONTAINER_OF(ptr, structure, member); +| link:debug.html[Debug layer] | Library debug layer -------------------------------------------------------------------------------- +| link:core_common.html[Common macros] | Common macros and semi-internal + interface -These common macros implements basic functions such as minimum, maximum, -absolute value, swap and sign. - -All macros use 'typeof()' in order to evaluate their arguments exactly once. - -The 'GP_ARRAY_SIZE()' macro computes size of statically defined array (i.e. -returns +sizeof(array) / sizeof(elem)+). - -The 'GP_CONTAINER_OF()' macro computes pointer to a structure given pointer to -its member. - -[source,c] -------------------------------------------------------------------------------- -#include <core/GP_Clamp.h> - -/* - * Clamps integer value to 8 bit unsigned value. - */ -GP_CLAMP_INT_0_255(val); - -/* - * Clamps integer value. - */ -GP_CLAMP(val, min, max); - -------------------------------------------------------------------------------- - -Value clamping macros. - -NOTE: this header is not included by including the 'GP.h' header. - -Temporary Buffer Allocator -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Temporary buffer allocator is used to allocate temporary buffer needed for -certain operations (mostly used in image filters). - -The intended usage of temporary buffers is: - -* Count sum of the size needed for all buffers -* Allocate temporary buffer of this size -* Partition the buffer into smaller blocks -* Use the blocks as needed -* Once operation is done, free the buffer - -The allocator code greatly simplifies these steps. Moreover it avoids memory -fragmentation by creating small buffers on the process stack (current theshold -is set to 2kB) and by grouping the temporary buffers into one continuous -region. - -NOTE: The allocator itself does not align the resulting blocks. It's your - responsibility to allocate the buffers in a way that the result is - adequately aligned (hint: the start of the block is aligned, so - get blocks that needs to be aligned first). - -[source,c] -------------------------------------------------------------------------------- -#include <core/GP_TempAlloc.h> - -/* - * A macro that creates block allocator. - * - * The name must be unique among variable and functions names. - * - * The bsize is actual size of the block allocated. - */ -GP_TempAllocCreate(name, bsize); - -/* - * A macro that returns pointer to the start of a block of a bsize - * partioned from the block allocator passed as self argument. - */ -GP_TempAllocGet(self, bsize); - -/* - * Free the allocator memory. - */ -GP_TempAllocFree(self); -------------------------------------------------------------------------------- - -Example usage of the allocator: - -[source,c] -------------------------------------------------------------------------------- -#include <core/GP_TempAlloc.h> - -int foo(...) -{ - GP_TempAllocCreate(tmp, 3 * img->width); - - uint8_t *R = GP_TempAllocGet(tmp, img->width); - uint8_t *G = GP_TempAllocGet(tmp, img->width); - uint8_t *B = GP_TempAllocGet(tmp, img->width); - - /* start of the code that uses the buffers */ - - ... - - if (error) { - GP_TempAllocFree(self); - return -1; - } - - ... - - /* end of the code that uses the buffers */ - - GP_TempAllocFree(self); - - return 0; -} -------------------------------------------------------------------------------- +| link:environment_variables.html[Environment variables] | Environment variables +|============================================================================= diff --git a/doc/core.txt b/doc/core_common.txt similarity index 100% copy from doc/core.txt copy to doc/core_common.txt diff --git a/doc/get_put_pixel.txt b/doc/get_put_pixel.txt index 3c5e716..86d90c7 100644 --- a/doc/get_put_pixel.txt +++ b/doc/get_put_pixel.txt @@ -43,7 +43,7 @@ void GP_PutPixel_Raw_{{ bpp }}(GP_Context *c, GP_Coord x, GP_Coord y, -------------------------------------------------------------------------------- These functions are generally fast, but does not honour context rotation flags -and do not check coordinates. +and do not check that coordinates are inside of the context. They are intended as basic building blocks for other GFX primitives, filters, etc. diff --git a/doc/pixels.txt b/doc/pixels.txt index d6c18e8..37553c4 100644 --- a/doc/pixels.txt +++ b/doc/pixels.txt @@ -10,7 +10,7 @@ Pixel Type ------------------------------------------------------------------------------- #include <GP.h> /* or */ -#include <core/GP_Pixel.h> +#include <core/GP_Pixel.gen.h> typedef enum GP_PixelType { GP_PIXEL_UNKNOWN, @@ -28,14 +28,15 @@ typedef enum GP_PixelType { /* * The same values are also defined as macros so it's possible to - * use them with ifdef as follows. + * use them with ifdef as: + * #ifdef GP_PIXEL_RGB555 + * ... + * #endif /* GP_PIXEL_RGB555 */ */ -#ifdef GP_PIXEL_RGB555 - +#define GP_PIXEL_UNKNOWN GP_PIXEL_UNKNOWN +#define GP_PIXEL_xRGB8888 GP_PIXEL_xRGB8888 ... -#endif /* GP_PIXEL_RGB555 */ - ------------------------------------------------------------------------------- Pixels are described by a pixel type, which is enumeration type. The enum is diff --git a/doc/progress_callback.txt b/doc/progress_callback.txt index 38719e7..e12dccf 100644 --- a/doc/progress_callback.txt +++ b/doc/progress_callback.txt @@ -1,9 +1,6 @@ Progress Callback ----------------- -Progress Callback -~~~~~~~~~~~~~~~~~ - The 'GP_ProgressCallback' is a structure that stores user-defined callback function and user-defined pointer and percentage. @@ -11,7 +8,8 @@ It is passed as last parameter to functions that would take some time to complete and adds capability to track the operation progress as well as to abort the operation. -Currently it's used for filters and loaders. +Currently it's used in link:filters.html[filters] and +link:loaders.html[loaders]. [source,c] ------------------------------------------------------------------------------- @@ -22,12 +20,21 @@ typdedef struct GP_ProgressCallback { } GP_ProgressCallback; ------------------------------------------------------------------------------- -If non 'NULL' progress callback structure is passed to a function, the -callback function is periodically called and the percentage is updated. +The 'callback' pointer is a pointer to user defined callback function. + +The 'priv' pointer can be used to pass a pointer to the callback function and +can accessed inside of the callback by defererencin the 'self' argument. + +The 'percentage' field is updated by the function the callback was passed to +and is increased monotonically till it reaches 100. + +If 'non-NULL' progress callback structure is passed to a function, it's called +periodically and the percentage field is updated. -The return value from callback could abort the function execution. If non zero -value is returned operation is aborted, all memory freed etc. and in case of -bitmap loaders 'errno' is set to 'ECANCELED'. +The return value from callback could abort the execution. If a non-zero value +is returned operation is aborted, all memory freed etc., in case of pixmap +loaders 'errno' is set to 'ECANCELED' and in case of pixmap savers the newly +created file is removed too. The callback, if supported, is the last parameter of a function. http://repo.or.cz/w/gfxprim.git/commit/282b616826f4ad7cfd9c3b804c649e61e56a9... commit 282b616826f4ad7cfd9c3b804c649e61e56a9b32 Author: Cyril Hrubis <metan@ucw.cz> Date: Sun Dec 1 19:56:28 2013 +0100 doc: Remove unused pixel_types.txt. Signed-off-by: Cyril Hrubis <metan@ucw.cz> diff --git a/doc/pixel_types.txt b/doc/pixel_types.txt deleted file mode 100644 index ee0111c..0000000 --- a/doc/pixel_types.txt +++ /dev/null @@ -1,56 +0,0 @@ -Supported pixel sizes ---------------------- - -The default maximum size of a single pixel is 32 bits. The limitations would -be analogous for other settings (8, 16 and 64). - -Pixel sizes 8, 16 and 32 are supported on all systems and generally very efficient -(assignment is used for all operations). 24 bpp is supported, but the operations may be -slightly slower. - -Pixel sizes 1, 2 and 4 depend on bit-endian setting and are supported on all systems. -Subcontext operations and blits may be slower in case of a different subpixel alignment. - -Pixel sizes not divisible by 8 and between 9 and 23 depend on the bit endian - -the endianity of the system must match the bit-endianity. The other combination -is not supported at all - it would be too complicated and probably very inefficient -to decode/encode. - -Pixel sizes between 25 and 31 are not supported at all, as these pixels might not fit -into a 32-bit byte-aligned window. - -The pixel sizes to be supported must be explicitly listed in the configuration file, -each including the bit-endian if required (see below). - -Supported pixel types ---------------------- - -The supported files are declared in the configuration file and must use only the declared -pixel sizes with bit-endians. RGB, monochrome and palette formats are supported, -all with optional alpha channel (the alpha support level for palette types is not decided yet). - -The pixel type - -System endianity ----------------- - -The library should work on both little-endian and big-endian systems. -Other variants than the standard (0123 and 3210) are not supported. - -In case of pixel sizes between 9 and 23 (except for 16), the system endianity must match the -selected bit endianity. It is safe to build the library with the disallowed combination -format, as long as it is not used (compile-time warning is generated). - -Bit-endianity -------------- - -With 1, 2 and 4 bpp formats, there are two possible orders of pixels within a byte, -both seen in the wild. The two are enumerated in `GP_BIT_ENDIAN`: - -`GP_BIT_ENDIAN_LE`:: - Less significant bits contain pixels with lower indices. - Also used for irrelevant bit-endian (8, 15, 24, 32bpp). -`GP_BIT_ENDIAN_BE`:: - More significant bits contain pixels with lower indices. - - http://repo.or.cz/w/gfxprim.git/commit/f63f5aa939d96a4abb0b345470dd7d92ab65a... commit f63f5aa939d96a4abb0b345470dd7d92ab65a360 Author: Cyril Hrubis <metan@ucw.cz> Date: Sun Dec 1 19:05:30 2013 +0100 doc: Autogenerate table of all examples + cleanup. Signed-off-by: Cyril Hrubis <metan@ucw.cz> diff --git a/doc/.gitignore b/doc/.gitignore index 670b96a..4731cc5 100644 --- a/doc/.gitignore +++ b/doc/.gitignore @@ -13,3 +13,5 @@ bit-endian-be-1bit.png bit-endian-be-2bits.png bit-endian-le-1bit.png bit-endian-le-2bits.png + +examples.txt diff --git a/doc/Makefile b/doc/Makefile index a9121f7..197e81d 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -21,6 +21,7 @@ GENIMAGES=discrete_linear_1D_convolution_alg1 discrete_linear_1D_convolution_alg PAGES=$(subst .txt,.html,$(SOURCES)) PAGES+=$(subst .txt,.html,$(EXAMPLE_SOURCES)) +PAGES+=examples.html .PHONY: toolcheck clean @@ -58,14 +59,18 @@ toolcheck: $(PAGES): %.html: %.txt asciidoc $(ASCIIDOC_PARAMS) $< -examples.html: examples.txt ../demos/c_simple/*.c ../demos/py_simple/*.py asciidoc.conf - asciidoc $(ASCIIDOC_PARAMS) -a toc examples.txt +# +# Autogenerate examples page +# +examples.txt: $(EXAMPLE_SOURCES) gen_examples_page.sh + ./gen_examples_page.sh examples.txt # # Clean up generated images # CLEAN+=$(patsubst %,%.md5,$(GENIMAGES)) CLEAN+=$(patsubst %,%.png,$(GENIMAGES)) +CLEAN+=examples.txt # # Clean up generated pages diff --git a/doc/asciidoc.conf b/doc/asciidoc.conf index 4cc241a..240991d 100644 --- a/doc/asciidoc.conf +++ b/doc/asciidoc.conf @@ -45,6 +45,7 @@ ifdef::toc2[<link rel="stylesheet" href="{stylesdir=.}/toc2.css" type="text/css" <li><a href="index.html">Home</a></li> <li><a href="about.html">About</a></li> <li><a href="compilation.html">Compilation</a></li> + <li><a href="examples.html">Examples</a></li> </ul> C API Pages <ul> diff --git a/doc/backends.txt b/doc/backends.txt index e124cca..46a631a 100644 --- a/doc/backends.txt +++ b/doc/backends.txt @@ -195,7 +195,8 @@ Currently the 'AA-lib' backend uses default initialization parameters. Way how to pass 'AA-lib' specific parameters will be added. This interface will likely change. -Overall init function +[[Backend_Init]] +Backend init function ~~~~~~~~~~~~~~~~~~~~~ Although there is no unified backend initialization, there is something close to @@ -436,6 +437,7 @@ queue and the call returns. } ------------------------------------------------------------------------------- +[[Timers]] GP_BackendAddTimer ^^^^^^^^^^^^^^^^^^ @@ -594,6 +596,7 @@ NOTE: The backend->context pointer may change upon calling this function and at least backend->context->pixels pointer will change. +[[ResizeAck]] GP_BackendResizeAck ^^^^^^^^^^^^^^^^^^^ diff --git a/doc/backends_python.txt b/doc/backends_python.txt index 65ff893..a5c2206 100644 --- a/doc/backends_python.txt +++ b/doc/backends_python.txt @@ -44,7 +44,7 @@ the other hand, has its own input queue. TIP: See multiple windows link:example_py_x11_windows.html[example]. - +[[Backend_Init]] BackendInit ^^^^^^^^^^^ diff --git a/doc/debug.txt b/doc/debug.txt index aedef2a..83cf91d 100644 --- a/doc/debug.txt +++ b/doc/debug.txt @@ -67,7 +67,7 @@ void GP_DebugPrint(int level, const char *file, const char *function, int line, ------------------------------------------------------------------------------- Printf-like macros used to print debug messages. All of them calls the -'GP_DebugPrint()' function with slightly parameters. +'GP_DebugPrint()' function with slightly different parameters. [source,c] ------------------------------------------------------------------------------- diff --git a/doc/example_SDL_glue.txt b/doc/example_SDL_glue.txt index aab453f..804898f 100644 --- a/doc/example_SDL_glue.txt +++ b/doc/example_SDL_glue.txt @@ -1,5 +1,5 @@ -SDL Glue Example ----------------- +SDL Glue +-------- You can easily mix SDL and GFXprim code using 'GP_ContextFromSDLSurface()' function. diff --git a/doc/example_backend.txt b/doc/example_backend.txt index ed13dea..55e7f16 100644 --- a/doc/example_backend.txt +++ b/doc/example_backend.txt @@ -1,5 +1,11 @@ -Graphics Backend Example ------------------------- +Graphics Backend +---------------- +This is a very simple backend example that shows how to use +link:backends.html#Backend_Init[backend init function] and +link:input.html[input event layer]. + +It also shows how to handle +link:backends.html#ResizeAck[window resize events]. [source,c] ------------------------------------------------------------------ diff --git a/doc/example_backend_timers.txt b/doc/example_backend_timers.txt index e9d479f..ce57a85 100644 --- a/doc/example_backend_timers.txt +++ b/doc/example_backend_timers.txt @@ -1,5 +1,6 @@ -Backend Timers Example ----------------------- +Backend Timers +-------------- +This example shows how to use link:backends.html#Timers[backend timers]. [source,c] ------------------------------------------------------------------ diff --git a/doc/example_debug_handler.txt b/doc/example_debug_handler.txt index a859f68..67f28ee 100644 --- a/doc/example_debug_handler.txt +++ b/doc/example_debug_handler.txt @@ -1,5 +1,7 @@ -Debug Message Handler Example ------------------------------ +Custom Debug Message Handler +---------------------------- +This example shows how to redirect link:debug.html[library debug messages] +into a custom debug message handler. [source,c] ------------------------------------------------------------------ diff --git a/doc/example_fonts.txt b/doc/example_fonts.txt index 85a6618..4c4b79b 100644 --- a/doc/example_fonts.txt +++ b/doc/example_fonts.txt @@ -1,6 +1,9 @@ -Font Test Example ------------------ -.A simple program to show all font characters with different styles. +Font and Text rendering +----------------------- + +Fonttest +~~~~~~~~ +A simple program to show all font characters with different styles. [source,c] ------------------------------------------------------------------ @@ -8,8 +11,8 @@ include::../demos/c_simple/fonttest.c[] ------------------------------------------------------------------ Fileview --------- -.A simple program to show contents of a file. +~~~~~~~~ +A simple program to show contents of a file. [source,c] ------------------------------------------------------------------ diff --git a/doc/example_gaussian_noise.txt b/doc/example_gaussian_noise.txt index 1f023d8..95b8a81 100644 --- a/doc/example_gaussian_noise.txt +++ b/doc/example_gaussian_noise.txt @@ -1,5 +1,6 @@ -Gaussian Additive Noise Filter Example --------------------------------------- +Gaussian Additive Noise Filter +------------------------------ +Simple program that adds a gaussian distributed noise to the image. [source,c] ------------------------------------------------------------------ diff --git a/doc/example_input.txt b/doc/example_input.txt index 15b7233..8132a26 100644 --- a/doc/example_input.txt +++ b/doc/example_input.txt @@ -1,5 +1,6 @@ -Input Events Example --------------------- +Input Events Handling +--------------------- +This example shows how to handle most of the link:input.html[input events]. [source,c] ------------------------------------------------------------------ diff --git a/doc/example_loader_registration.txt b/doc/example_loader_registration.txt index b287560..fd4f348 100644 --- a/doc/example_loader_registration.txt +++ b/doc/example_loader_registration.txt @@ -1,5 +1,10 @@ -Image Loader Registration Example ---------------------------------- +Image Loader Registration +------------------------- +This example shows how to +link:loaders.html#Register_Loader[register custom image loader] +so that library functions such as +link:loaders.html#Load_Image[GP_LoadImage()] and +link:loaders.html#Save_Image[GP_SaveImage()] can use it. [source,c] ------------------------------------------------------------------ diff --git a/doc/example_loaders_progress_callback.txt b/doc/example_loaders_progress_callback.txt index 7da5160..6024c74 100644 --- a/doc/example_loaders_progress_callback.txt +++ b/doc/example_loaders_progress_callback.txt @@ -1,5 +1,7 @@ -Graphics Backend Example ------------------------- +Loaders with Progress Callback +------------------------------ +This example shows how to use link:progress_callback.html[progress callback] +together with link:loaders.html[image loaders functions]. [source,c] ------------------------------------------------------------------ diff --git a/doc/example_py_backends.txt b/doc/example_py_backends.txt index 625084c..5ff7213 100644 --- a/doc/example_py_backends.txt +++ b/doc/example_py_backends.txt @@ -1,6 +1,7 @@ Backend Init ------------ -.A simple program to demonstrate backend init function. +A simple program to demonstrate +link:backends_python.html#Backend_Init[backend init function]. [source,python] ------------------------------------------------------------------ diff --git a/doc/example_py_blur.txt b/doc/example_py_blur.txt index cfe5577..c8ab4d1 100644 --- a/doc/example_py_blur.txt +++ b/doc/example_py_blur.txt @@ -1,6 +1,6 @@ -Gaussian Blur Example ---------------------- -.A simple program that loads image, blurs it and saves result +Gaussian Blur Filter +-------------------- +A simple program that loads image, blurs it and saves result. [source,python] ------------------------------------------------------------------ diff --git a/doc/example_py_convolution.txt b/doc/example_py_convolution.txt index 0cdfe06..58ee950 100644 --- a/doc/example_py_convolution.txt +++ b/doc/example_py_convolution.txt @@ -1,6 +1,6 @@ -Block Blur Convolution Example ------------------------------- -.A simple program that loads image, blurs it and saves result +Box Blur Convolution +-------------------- +A simple program that loads image, blurs it and saves result. [source,python] ------------------------------------------------------------------ diff --git a/doc/example_py_dithering.txt b/doc/example_py_dithering.txt index d187c7d..6b3fd9e 100644 --- a/doc/example_py_dithering.txt +++ b/doc/example_py_dithering.txt @@ -1,6 +1,6 @@ -Dithering Example ------------------ -.A simple program that loads image, dithers it and saves result +Floyd-Steinberg Dithering +------------------------- +A simple program that loads image, dithers it and saves result. [source,python] ------------------------------------------------------------------ diff --git a/doc/example_py_gfx.txt b/doc/example_py_gfx.txt index 2c8854d..4102f96 100644 --- a/doc/example_py_gfx.txt +++ b/doc/example_py_gfx.txt @@ -1,6 +1,6 @@ -Gfx ---- -.A simple program to show how to use gfx +GFX Primitives +-------------- +A simple program to show how to use most of the graphics primitives. [source,python] ------------------------------------------------------------------ diff --git a/doc/example_py_showimage.txt b/doc/example_py_showimage.txt index 10e6e51..608d500 100644 --- a/doc/example_py_showimage.txt +++ b/doc/example_py_showimage.txt @@ -1,6 +1,6 @@ Showimage --------- -.A simple program to load and show image +A very simple program that loads an image and shows it in a window. [source,python] ------------------------------------------------------------------ diff --git a/doc/example_py_x11_windows.txt b/doc/example_py_x11_windows.txt index 7d454a9..d077760 100644 --- a/doc/example_py_x11_windows.txt +++ b/doc/example_py_x11_windows.txt @@ -1,6 +1,6 @@ -X11 Windows ------------ -.A simple program to demonstrate multiple windows with X11 +X11 backend with multiple windows +--------------------------------- +A simple program to demonstrate multiple windows on X11 backend. [source,python] ------------------------------------------------------------------ diff --git a/doc/example_v4l2.txt b/doc/example_v4l2.txt index 2f1e389..cfa6de9 100644 --- a/doc/example_v4l2.txt +++ b/doc/example_v4l2.txt @@ -1,7 +1,8 @@ -Graphics Backend Example +Grabbers (v4l2) Examples ------------------------ -Simple grabber that saves images taken from v4l2 device. +Simple link:grabbers.html[grabber example] that saves images taken from v4l2 +device. [source,c] ------------------------------------------------------------------ diff --git a/doc/example_x11_windows.txt b/doc/example_x11_windows.txt index 4e4bb31..a5f0406 100644 --- a/doc/example_x11_windows.txt +++ b/doc/example_x11_windows.txt @@ -1,6 +1,6 @@ -Graphics Backend Example ------------------------- -.An example how to create and manage two windows using the X11 backend +X11 Backend with multiple windows +--------------------------------- +This example shows how to create multiple X11 windows. [source,c] ------------------------------------------------------------------ diff --git a/doc/examples.txt b/doc/examples.txt index 0f6566b..d96b7f8 100644 --- a/doc/examples.txt +++ b/doc/examples.txt @@ -1,122 +1,38 @@ -Image loaders examples ----------------------- - -Loads an image and saves it into 'out.png' png image. - -Example in C -~~~~~~~~~~~~ - -[source,c] ------------------------------------------------------------------- -include::../demos/c_simple/loaders_example.c[] ------------------------------------------------------------------- - -Example in C utilizing progress callback -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -[source,c] ------------------------------------------------------------------- -include::../demos/c_simple/loaders.c[] ------------------------------------------------------------------- - -Example in C using image meta-data interface -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -[source,c] ------------------------------------------------------------------- -include::../demos/c_simple/meta_data.c[] ------------------------------------------------------------------- - -[source,c] ------------------------------------------------------------------- -include::../demos/c_simple/meta_data_dump.c[] ------------------------------------------------------------------- - -Example in Python -~~~~~~~~~~~~~~~~~ - -[source,python] ------------------------------------------------------------------- -include::../demos/py_simple/loaders_example.py[] ------------------------------------------------------------------- - -GFX Examples ------------- - -Drawing Lines -~~~~~~~~~~~~~ - -Example in C -^^^^^^^^^^^^ - -[source,c] ------------------------------------------------------------------- -include::../demos/c_simple/gfx_koch.c[] ------------------------------------------------------------------- - -Filters -------- - -Symmetry filters (Rotation, Mirroring) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Example in C -^^^^^^^^^^^^ - -[source,c] ------------------------------------------------------------------- -include::../demos/c_simple/filters_symmetry.c[] ------------------------------------------------------------------- - -Example in Python -^^^^^^^^^^^^^^^^^ - -[source,python] ------------------------------------------------------------------- -include::../demos/py_simple/rotate90.py[] ------------------------------------------------------------------- - -Simple backend example ----------------------- - -Basic backend code example. Initalizes backends, draws a cross and dumps -events. - -Example in C -~~~~~~~~~~~~ - -[source,c] ------------------------------------------------------------------- -include::../demos/c_simple/backend_example.c[] ------------------------------------------------------------------- - -[source,c] ------------------------------------------------------------------- -include::../demos/c_simple/showimage.c[] ------------------------------------------------------------------- - -Grabbers --------- - -Simple C source that saves JPEG images from V4L2 device (web camera). - -[source,c] ------------------------------------------------------------------- -include::../demos/c_simple/v4l2_grab.c[] ------------------------------------------------------------------- - -Simple C source that shows filters interactively on image stream from a -camera. - -[source,c] ------------------------------------------------------------------- -include::../demos/c_simple/v4l2_show.c[] ------------------------------------------------------------------- - -GFXprim + PyGTK ---------------- - -[source,python] ------------------------------------------------------------------- -include::../demos/py_simple/pygtk_example.py[] ------------------------------------------------------------------- +List of examples +---------------- +Following pages contains a list of all code examples, the source +files could be found and are compiled in the +demos/c_simple/+ and ++demos/py_simple+ directories in the source tree. + +.List C examples +[grid="rows"] +[options="autowidth,header",cols="<,<m"] +|=========================== +| Example | Source filename(s) +| link:example_SDL_glue.html[SDL Glue] | SDL_glue.c +| link:example_backend.html[Graphics Backend] | backend_example.c +| link:example_backend_timers.html[Backend Timers] | backend_timers_example.c +| link:example_debug_handler.html[Custom Debug Message Handler] | debug_handler.c +| link:example_fonts.html[Font and Text rendering] | fonttest.c +fileview.c +| link:example_gaussian_noise.html[Gaussian Additive Noise Filter] | gaussian_noise.c +| link:example_input.html[Input Events Handling] | input_example.c +| link:example_loader_registration.html[Image Loader Registration] | loaders_register.c +| link:example_loaders_progress_callback.html[Loaders with Progress Callback] | loaders.c +| link:example_v4l2.html[Grabbers (v4l2) Examples] | v4l2_grab.c +v4l2_show.c +| link:example_x11_windows.html[X11 Backend with multiple windows] | x11_windows.c +|=========================== +.List Python examples +[grid="rows"] +[options="autowidth,header",cols="<,<m"] +|=========================== +| Example | Source filename(s) +| link:example_py_backends.html[Backend Init] | backends.py +| link:example_py_blur.html[Gaussian Blur Filter] | blur.py +| link:example_py_convolution.html[Box Blur Convolution] | convolution.py +| link:example_py_dithering.html[Floyd-Steinberg Dithering] | dither.py +| link:example_py_gfx.html[GFX Primitives] | gfx.py +| link:example_py_showimage.html[Showimage] | showimage.py +| link:example_py_x11_windows.html[X11 backend with multiple windows] | x11_windows.py +|=========================== diff --git a/doc/gen_examples_page.sh b/doc/gen_examples_page.sh new file mode 100755 index 0000000..eb94a4d --- /dev/null +++ b/doc/gen_examples_page.sh @@ -0,0 +1,56 @@ +#!/bin/sh +# +# Autogenerate examples page +# +OUT="$1" + +get_names() +{ + LINKS=$(grep 'include:.*' $1) + NAMES=$(echo $LINKS | sed 's/include:://g' | sed 's/[]//g') + for i in $NAMES; do + echo $(basename $i) + done +} + +table_header() +{ + echo ".List $1 examples" >> $OUT + echo "[grid="rows"]" >> $OUT + echo '[options="autowidth,header",cols="<,<m"]' >> $OUT + echo "|===========================" >> $OUT + echo "| Example | Source filename(s)" >> $OUT +} + +table_footer() +{ + echo "|===========================" >> $OUT +} + +echo "List of examples" > $OUT +echo "----------------" >> $OUT +echo "Following pages contains a list of all code examples, the source " >> $OUT +echo "files could be found and are compiled in the +demos/c_simple/+ and" >> $OUT +echo "+demos/py_simple+ directories in the source tree." >> $OUT +echo >> $OUT + +table_header "C" +for i in example_*.txt; do + LINK=$(echo $i | sed s/.txt/.html/) + DESC=$(head -n 1 $i) + FNAMES=$(get_names "$i") + if $(echo $i | grep -q '_py_'); then + continue + fi + echo "| link:$LINK[$DESC] | $FNAMES" >> $OUT +done +table_footer + +table_header "Python" +for i in example_py_*.txt; do + LINK=$(echo $i | sed s/.txt/.html/) + DESC=$(head -n 1 $i) + FNAMES=$(get_names "$i") + echo "| link:$LINK[$DESC] | $FNAMES" >> $OUT +done +table_footer diff --git a/doc/loaders.txt b/doc/loaders.txt index 3b8e283..b42c47e 100644 --- a/doc/loaders.txt +++ b/doc/loaders.txt @@ -8,8 +8,8 @@ saving and GIF, JPEG2000 and PSP for loading. Have a look at the link:about.html#Loaders[supported formats]. -Loaders API -~~~~~~~~~~~ +Image Loaders and Savers +~~~~~~~~~~~~~~~~~~~~~~~~ All loading functions returns a pointer to allocated and loaded image or upon a failure 'NULL'. @@ -18,12 +18,10 @@ All saving functions returns zero on success and non-zero on failure. If image saving is aborted by a callback, the opened file is closed and removed from a filesystem before the call returns. -In case of a failure 'errno' is set. - The signature matching functions takes a 32 bytes long buffer and looks for a -valid image signature. If signature is found 1 is returned. +valid image signature. If signature is found non-zero is returned. -The possible 'errno' values are: +In case of a failure 'errno' is set, possible 'errno' values are: * anything returned by +open()+, +close()+, +lseek()+, +read()+, +write()+, ... - 'ENOENT' if file doesn't exist @@ -38,9 +36,8 @@ The possible 'errno' values are: You can get more information about the error condition by turning on GFXprim link:environment_variables.html#GP_DEBUG[debug messages]. -Image Loader -~~~~~~~~~~~~ +[[Load_Image]] [source,c] ------------------------------------------------------------------------------- #include <loaders/GP_Loader.h> @@ -66,6 +63,7 @@ is returned. If file extension disagrees with file signature on the file format a warning is printed into the 'stderr'. +[[Save_Image]] [source,c] ------------------------------------------------------------------------------- #include <loaders/GP_Loader.h> @@ -89,8 +87,9 @@ wasn't compiled with support for this image type). If context pixel type is not supported by the format 'errno' is set to 'EINVAL'. -Advanced usage -^^^^^^^^^^^^^^ +[[Register_Loader]] +Advanced Loaders usage +^^^^^^^^^^^^^^^^^^^^^^ [source,c] ------------------------------------------------------------------------------- @@ -161,10 +160,10 @@ extensions that are commonly used for this image format. All internal loaders are all described in list of this structures which is used to implement functions such as 'GP_LoadImage()'. -You can print currently active loaders via the 'GP_ListLoaders()' register and +You can print currently active loaders via the 'GP_ListLoaders()'. Register and unregister your own loaders by 'GP_LoaderRegister()' and 'GP_LoaderUnregister()'. Once image loader is registered the generic loading -functions could use it to load and save images. +functions can use it to load and save images. TIP: For example usage see image loader registration link:example_loader_registration.html[example]. ----------------------------------------------------------------------- Summary of changes: doc/.gitignore | 2 + doc/Makefile | 11 ++- doc/asciidoc.conf | 2 + doc/backends.txt | 5 +- doc/backends_python.txt | 2 +- doc/context.txt | 33 ++++-- doc/core.txt | 167 ++++++----------------------- doc/{core.txt => core_common.txt} | 0 doc/debug.txt | 2 +- doc/example_SDL_glue.txt | 4 +- doc/example_backend.txt | 10 ++- doc/example_backend_timers.txt | 5 +- doc/example_debug_handler.txt | 6 +- doc/example_fonts.txt | 13 ++- doc/example_gaussian_noise.txt | 5 +- doc/example_input.txt | 5 +- doc/example_loader_registration.txt | 9 ++- doc/example_loaders_progress_callback.txt | 6 +- doc/example_py_backends.txt | 3 +- doc/example_py_blur.txt | 6 +- doc/example_py_convolution.txt | 6 +- doc/example_py_dithering.txt | 6 +- doc/example_py_gfx.txt | 6 +- doc/example_py_showimage.txt | 2 +- doc/example_py_x11_windows.txt | 6 +- doc/example_v4l2.txt | 5 +- doc/example_x11_windows.txt | 6 +- doc/examples.txt | 160 +++++++--------------------- doc/gen_examples_page.sh | 56 ++++++++++ doc/get_put_pixel.txt | 2 +- doc/loaders.txt | 23 ++-- doc/pixel_types.txt | 56 ---------- doc/pixels.txt | 13 ++- doc/progress_callback.txt | 25 +++-- 34 files changed, 271 insertions(+), 397 deletions(-) copy doc/{core.txt => core_common.txt} (100%) create mode 100755 doc/gen_examples_page.sh delete mode 100644 doc/pixel_types.txt repo.or.cz automatic notification. Contact project admin jiri.bluebear.dluhos@gmail.com if you want to unsubscribe, or site admin admin@repo.or.cz if you receive no reply. -- gfxprim.git ("A simple 2D graphics library with emphasis on correctness and well-defined operation.")