[repo.or.cz] gfxprim.git branch master updated: 32789015536313fb5dd49b14c5acbf28f8959027
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 32789015536313fb5dd49b14c5acbf28f8959027 (commit) via 63d359a15e81ae6f4aee95e3d771240869a68b15 (commit) from e5413bf88214d6a7a13b0ad251befe8098a5e387 (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/32789015536313fb5dd49b14c5acbf28f8959... commit 32789015536313fb5dd49b14c5acbf28f8959027 Author: Cyril Hrubis <metan@ucw.cz> Date: Sat Jan 12 14:32:22 2013 +0100 doc: Add simple floating menu. diff --git a/doc/asciidoc.conf b/doc/asciidoc.conf index bf03dc0..d7cd14c 100644 --- a/doc/asciidoc.conf +++ b/doc/asciidoc.conf @@ -31,54 +31,51 @@ asciidoc.install({toc,toc2?{toclevels}}); /*]]>*/ </script> endif::disable-javascript[] -ifdef::asciimath[] -<script type="text/javascript" src="{scriptsdir=.}/ASCIIMathML.js"></script> -endif::asciimath[] -ifdef::latexmath[] -<script type="text/javascript" src="{scriptsdir=.}/LaTeXMathML.js"></script> -endif::latexmath[] {docinfo1,docinfo2#}{include:{docdir}/docinfo.html} {docinfo,docinfo2#}{include:{docdir}/{docname}-docinfo.html} </head> <body class="{doctype}" style="max-width:55em; margin-left: auto; margin-right: auto;"> + # Article, book header. -<div class="logo"> -<h1>GFXprim documentation</h1> +# Left menu +<div class="left-menu"> + <h4>Navigation</h4> + <ul> + <li><a href="general.html">Home</a></li> + <li><a href="api.html">API</a></li> + <li><a href="examples.html">Examples</a></li> + </ul> </div> -ifndef::doctype-manpage[] -<div id="header"> + +# Rest of the content +<div> + <div class="logo"> + <h1>GFXprim documentation</h1> + </div> + + <div id="header"> + ifndef::notitle[<h1>{doctitle}</h1>] ifdef::doctitle[] -<span id="author">{author}</span><br /> -<span id="email"><tt><<a href="mailto:{email}">{email}</a>></tt></span><br /> -<span id="revnumber">version {revnumber}{revdate?,}</span> -<span id="revdate">{revdate}</span> -<br /><span id="revremark">{revremark}</span> + <span id="author">{author}</span><br /> + <span id="email"><tt><<a href="mailto:{email}">{email}</a>></tt></span><br /> + <span id="revnumber">version {revnumber}{revdate?,}</span> + <span id="revdate">{revdate}</span> + <br /><span id="revremark">{revremark}</span> endif::doctitle[] + ifdef::toc,toc2[{template:toc}] -</div> -endif::doctype-manpage[] -# Man page header. -ifdef::doctype-manpage[] -<div id="header"> -<h1> -{doctitle} Manual Page -</h1> -ifdef::toc,toc2[{template:toc}] -<h2>{manname-title}</h2> -<div class="sectionbody"> -<p>{manname} - - {manpurpose} -</p> -</div> -</div> -endif::doctype-manpage[] -<div class="content"> + + </div> + + <div class="content"> + [footer] -<div id="footer"> -<div id="footer-text"> + <div id="footer"> + <div id="footer-text"> template::[footer-text] + </div> </div> ifdef::badges[] <div id="footer-badges"> diff --git a/doc/asciidoc.css b/doc/asciidoc.css index 4b19932..4a1cada 100644 --- a/doc/asciidoc.css +++ b/doc/asciidoc.css @@ -115,6 +115,13 @@ pre { margin-bottom: 1.5em; } +div.left-menu { + position: relative; + top: 140pt; + left: -100pt; + width: 30pt; +} + div.logo h1 { border-bottom: 0px; margin-top: 1em; http://repo.or.cz/w/gfxprim.git/commit/63d359a15e81ae6f4aee95e3d771240869a68... commit 63d359a15e81ae6f4aee95e3d771240869a68b15 Author: Cyril Hrubis <metan@ucw.cz> Date: Sat Jan 12 13:58:12 2013 +0100 doc: More work on the Core docs. diff --git a/doc/Makefile b/doc/Makefile index 23d87e7..a43432d 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -1,7 +1,8 @@ SOURCES=general.txt context.txt loaders.txt filters.txt basic_types.txt drawing_api.txt backends.txt gamma.txt grabbers.txt environment_variables.txt debug.txt core.txt api.txt input.txt - gen.txt pixels.txt coordinate_system.txt coding_style.txt + gen.txt pixels.txt coordinate_system.txt coding_style.txt + get_put_pixel.txt blits.txt progress_callback.txt EXAMPLE_SOURCES=$(wildcard example_*.txt) diff --git a/doc/blits.txt b/doc/blits.txt new file mode 100644 index 0000000..e2982e6 --- /dev/null +++ b/doc/blits.txt @@ -0,0 +1,75 @@ +Blits +----- + +NOTE: You may want to see the link:coordinate_system.html[coordinate system] first. + +Blit copies a rectangular area from one pixmap into the another one. Blits can +do automatic pixel conversion i.e. swap R a B in blit from RGB888 to BGR888 or +even convert RGB image into grayscale. + +The conversion however may not be ideal as the pixel channel values are just +divided/multiplied before they are written into the destination bitmap. For +down-sampling (i.e. size or number of channels of destination bitmap is +smaller) you should consider using the link:filters.html#Dithering[dithering +filters] first to convert the source bitmap into destination format. + +Also blits that do conversions are significantly slower than blits with equal +pixel sizes. If you need to blit a pixmap several times consider converting it +into destination pixel type to speed up the blitting. + + +[source,c] +-------------------------------------------------------------------------------- +#include <GP.h> +/* or */ +#include <core/GP_Blit.h> + +void GP_Blit(const GP_Context *src, + GP_Coord x0, GP_Coord y0, GP_Size w0, GP_Size h0, + GP_Context *dst, GP_Coord x1, GP_Coord y1); + +void GP_BlitXYWH(const GP_Context *src, + GP_Coord x0, GP_Coord y0, GP_Size w0, GP_Size h0, + GP_Context *dst, GP_Coord x1, GP_Coord y1); + +void GP_BlitXYXY(const GP_Context *src, + GP_Coord x0, GP_Coord y0, GP_Coord x1, GP_Coord y1, + GP_Context *dst, GP_Coord x2, GP_Coord y2); +-------------------------------------------------------------------------------- + +Blit functions to copy rectangular area from source to destination. + +As you may see the 'GP_Blit()' function is just alias for 'GP_BlitXYWH()'. + +WARNING: For these functions the behavior is undefined when you pass + coordinates or width or height outside of the source or destination + pixmap. If you need safe variant that automatically clips the + coordinates and rectangle to fit both the source and destination use + the Clipped variants described bellow. + + +[source,c] +-------------------------------------------------------------------------------- +#include <GP.h> +/* or */ +#include <core/GP_Blit.h> + +void GP_BlitXYXY_Clipped(const GP_Context *src, + GP_Coord x0, GP_Coord y0, GP_Coord x1, GP_Coord y1, + GP_Context *dst, GP_Coord x2, GP_Coord y2); + + +void GP_BlitXYWH_Clipped(const GP_Context *src, + GP_Coord x0, GP_Coord y0, GP_Size w0, GP_Size h0, + GP_Context *dst, GP_Coord x1, GP_Coord y1); + +void GP_Blit_Clipped(const GP_Context *src, + GP_Coord x0, GP_Coord y0, GP_Size w0, GP_Size h0, + GP_Context *dst, GP_Coord x1, GP_Coord y1); +-------------------------------------------------------------------------------- + +Blit functions to copy rectangular area from source to destination. Both +source and destination coordinates and sizes are clipped to fit the pixmaps. + +As you may see the 'GP_Blit_Clipped()' function is just alias for +'GP_BlitXYWH_Clipped()'. diff --git a/doc/core.txt b/doc/core.txt index a59938d..eb38437 100644 --- a/doc/core.txt +++ b/doc/core.txt @@ -1,14 +1,8 @@ -Library Core ------------- +Common code in Core +------------------- -The core of the library contains the 'GP_Context' structure which describes -in-memory bitmap (see context) as well as the most basic functionality (i.e. -reading/writing pixels, gamma handling, blits, progress callback, debug -printing...). More complex parts of the core library are discussed in separate -pages. - -Some of the interfaces described here (most notably the allocator) are -semi-internal interfaces and as such the API may change in the future. +NOTE: Some of the interfaces described here (most notably the allocator) are + semi-internal interfaces and as such API is not considered stable. Common Macros and Inline Functions ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -56,39 +50,6 @@ Value clamping macros. NOTE: this header is not included by including the 'GP.h' header. -Progress Callback -~~~~~~~~~~~~~~~~~ - -The 'GP_ProgressCallback' is a structure that stores user-defined callback -function and user-defined pointer and percentage. - -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. - -[source,c] -------------------------------------------------------------------------------- -typdedef struct GP_ProgressCallback { - float percentage; - int (*callback)(struct GP_ProgressCallback *self); - void *priv; -} 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 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 callback, if supported, is the last parameter of a function. - -TIP: For example usage see progress callback -link:example_loaders_progress_callback.html[example]. - Temporary Buffer Allocator ~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/doc/general.txt b/doc/general.txt index d71ec1f..2cd8776 100644 --- a/doc/general.txt +++ b/doc/general.txt @@ -3,18 +3,49 @@ General information Gfxprim is simple modular 2D bitmap graphics library with emphasis on speed and correctness. -One of the key points of the library is code generation. Most of the graphics -operations are written using 'jinja' templating engine which is used to -generate specialized C code. So, for an example, once you add pixel -definition into configuration file, creating specialized filters, loaders and -conversions to other pixel formats is just a matter of typing "make && make -clean". +One of the key points of the library is meta-programming. Most of the +operations and filters are wriiten in http://jinja.pocoo.org/[Jinja] +templating language that is used to generate specialized code in C +programmming language. Creating code that works with less usuall pixel types +should be as easy as adding pixel definition into the configuration and +rebuilding the library. Read more link:gen.html[here]. + +Parts of the library +~~~~~~~~~~~~~~~~~~~~ -The library also includes, fairly optimized, fixed-point image filters, namely -various resampling algorithms used to resize images, low pass filters, etc... +Core +^^^^ -Implemented features -~~~~~~~~~~~~~~~~~~~~ +Core of the library contains minimal amount of code to define interface that +is shared between all parts of the library. + +The most important part of the core is link:context.html[CP_Context] structure +that represents in-memory pixmap. + +The Core also contains generated code for basic operations such as +link:get_put_pixel.html[GetPixel] and link:get_put_pixel.html[PutPixel] and +optimized code for writing continous line of pixels 'GP_WritePixels' that are +base for the more complex drawing primitives in GFX or for graphics operations +in Filters. + +link:blits.html[Blits] are functions used to copy part of one bitmap into +another bitmap. The blits be also used for primitive bitmap pixel type +conversions (i.e. RGB888 vs BGR888). + +link:progress_callback.html[Progress Callback] is an interface that allows you +to monitor progress of an operation it is mainly used in loaders and filters. +Generally any operation that is not really quick takes optional pointer to +progress callback that allows your program to monitor and possibly abort the +operation. + +link:debug.html[Debug] interface is used as unified facility to print debug +messages, control debug level, etc. + +There is also support for link:gamma.html[Gamma] correction. Unfortunatelly +not all parts of library use it at the moment. + +And last but not least Core is a home for some link:core.html[common macros] +that are used from different parts of the library. Graphics Rendering ^^^^^^^^^^^^^^^^^^ diff --git a/doc/get_put_pixel.txt b/doc/get_put_pixel.txt new file mode 100644 index 0000000..f96354f --- /dev/null +++ b/doc/get_put_pixel.txt @@ -0,0 +1,15 @@ +GetPixel and PutPixel +--------------------- + +[source,c] +-------------------------------------------------------------------------------- +#include <GP.h> +/* or */ +#include <core/GP_GetPutPixel.h> + +GP_Pixel GP_GetPixel(const GP_Context *context, GP_Coord x, GP_Coord y); + +void GP_PutPixel(GP_Context *context, GP_Coord x, GP_Coord y, GP_Pixel p); +-------------------------------------------------------------------------------- + +TODO: This is stub. diff --git a/doc/progress_callback.txt b/doc/progress_callback.txt new file mode 100644 index 0000000..38719e7 --- /dev/null +++ b/doc/progress_callback.txt @@ -0,0 +1,35 @@ +Progress Callback +----------------- + +Progress Callback +~~~~~~~~~~~~~~~~~ + +The 'GP_ProgressCallback' is a structure that stores user-defined callback +function and user-defined pointer and percentage. + +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. + +[source,c] +------------------------------------------------------------------------------- +typdedef struct GP_ProgressCallback { + float percentage; + int (*callback)(struct GP_ProgressCallback *self); + void *priv; +} 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 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 callback, if supported, is the last parameter of a function. + +TIP: For example usage see progress callback +link:example_loaders_progress_callback.html[example]. ----------------------------------------------------------------------- Summary of changes: doc/Makefile | 3 +- doc/asciidoc.conf | 67 +++++++++++++++++++--------------------- doc/asciidoc.css | 7 ++++ doc/blits.txt | 75 +++++++++++++++++++++++++++++++++++++++++++++ doc/core.txt | 47 ++------------------------- doc/general.txt | 51 ++++++++++++++++++++++++------ doc/get_put_pixel.txt | 15 +++++++++ doc/progress_callback.txt | 35 +++++++++++++++++++++ 8 files changed, 211 insertions(+), 89 deletions(-) create mode 100644 doc/blits.txt create mode 100644 doc/get_put_pixel.txt create mode 100644 doc/progress_callback.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.")
participants (1)
-
metan