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 e90eda658220809b70c37e954d2624e3cfdcd5ea (commit)
from aaa7f50197c97d3b9b7f5d30cbe1f91c51f52384 (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/e90eda658220809b70c37e954d2624e3cfdc…
commit e90eda658220809b70c37e954d2624e3cfdcd5ea
Author: Cyril Hrubis <metan(a)ucw.cz>
Date: Sat Nov 10 17:27:32 2012 +0100
doc: Move ProgressCallback to core, add example.
diff --git a/doc/basic_types.txt b/doc/basic_types.txt
index f02688a..1542083 100644
--- a/doc/basic_types.txt
+++ b/doc/basic_types.txt
@@ -88,33 +88,3 @@ void GP_ColorLoadContextPixels(GP_Pixel pixels[], GP_Context *context);
Loads array of 'GP_Pixel' of size 'GP_COL_MAX', the array is then used with
the GP_Color enum as 'pixels[GP_COL_BLACK]'.
-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.
-
diff --git a/doc/core.txt b/doc/core.txt
index fdb8056..3e20ee2 100644
--- a/doc/core.txt
+++ b/doc/core.txt
@@ -56,6 +56,39 @@ 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.
+
+For example usage see progress callback
+link:example_loaders_progress_callback.html[example].
+
Temporary Buffer Allocator
~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/doc/example_loaders_progress_callback.txt b/doc/example_loaders_progress_callback.txt
new file mode 100644
index 0000000..7da5160
--- /dev/null
+++ b/doc/example_loaders_progress_callback.txt
@@ -0,0 +1,7 @@
+Graphics Backend Example
+------------------------
+
+[source,c]
+------------------------------------------------------------------
+include::../demos/c_simple/loaders.c[]
+------------------------------------------------------------------
-----------------------------------------------------------------------
Summary of changes:
doc/basic_types.txt | 30 ------------------
doc/core.txt | 33 ++++++++++++++++++++
...d.txt => example_loaders_progress_callback.txt} | 2 +-
3 files changed, 34 insertions(+), 31 deletions(-)
copy doc/{example_backend.txt => example_loaders_progress_callback.txt} (80%)
repo.or.cz automatic notification. Contact project admin jiri.bluebear.dluhos(a)gmail.com
if you want to unsubscribe, or site admin admin(a)repo.or.cz if you receive
no reply.
--
gfxprim.git ("A simple 2D graphics library with emphasis on correctness and well-defined operation.")
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 aaa7f50197c97d3b9b7f5d30cbe1f91c51f52384 (commit)
via 5c61bb13e751a867d68d1443e20b80a992ae1e11 (commit)
from fd437dffad5c449ae3dff083562b0db30ea1eb8e (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/aaa7f50197c97d3b9b7f5d30cbe1f91c51f5…
commit aaa7f50197c97d3b9b7f5d30cbe1f91c51f52384
Author: Cyril Hrubis <metan(a)ucw.cz>
Date: Sat Nov 10 17:07:02 2012 +0100
doc: Add more examples and links.
diff --git a/doc/backends.txt b/doc/backends.txt
index 66728f7..a471652 100644
--- a/doc/backends.txt
+++ b/doc/backends.txt
@@ -10,6 +10,8 @@ controlling the drawing.
So far there are three backends implemented, Linux mmaped frame-buffer, libSDL
and X11 backend.
+For example usage see backend link:example_backend.html[example].
+
Initialization functions
~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/doc/example_backend.txt b/doc/example_backend.txt
new file mode 100644
index 0000000..ed13dea
--- /dev/null
+++ b/doc/example_backend.txt
@@ -0,0 +1,7 @@
+Graphics Backend Example
+------------------------
+
+[source,c]
+------------------------------------------------------------------
+include::../demos/c_simple/backend_example.c[]
+------------------------------------------------------------------
diff --git a/doc/example_v4l2.txt b/doc/example_v4l2.txt
new file mode 100644
index 0000000..2f1e389
--- /dev/null
+++ b/doc/example_v4l2.txt
@@ -0,0 +1,17 @@
+Graphics Backend Example
+------------------------
+
+Simple grabber that saves images taken from v4l2 device.
+
+[source,c]
+------------------------------------------------------------------
+include::../demos/c_simple/v4l2_grab.c[]
+------------------------------------------------------------------
+
+More sophisticated example utilizing v4l2 device and
+link:backends.html[backends].
+
+[source,c]
+------------------------------------------------------------------
+include::../demos/c_simple/v4l2_show.c[]
+------------------------------------------------------------------
diff --git a/doc/grabbers.txt b/doc/grabbers.txt
index 93af01b..a794847 100644
--- a/doc/grabbers.txt
+++ b/doc/grabbers.txt
@@ -8,6 +8,8 @@ There is currently V4L2 driver that implements a grabber.
To link against grabbers use +-lGP_grabbers+ or better
+`gfxprim-config --libs-grabbers`+ in your linker flags.
+For example usage see grabber link:example_v4l2.html[examples].
+
Grabber API
~~~~~~~~~~~
http://repo.or.cz/w/gfxprim.git/commit/5c61bb13e751a867d68d1443e20b80a992ae…
commit 5c61bb13e751a867d68d1443e20b80a992ae1e11
Author: Cyril Hrubis <metan(a)ucw.cz>
Date: Sat Nov 10 16:55:08 2012 +0100
doc: Remove the all-in-one page API docs.
diff --git a/doc/Makefile b/doc/Makefile
index 19b89d2..4160ae0 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -1,6 +1,6 @@
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
+ environment_variables.txt debug.txt core.txt api.txt
EXAMPLE_SOURCES=$(wildcard example_*.txt)
@@ -14,13 +14,7 @@ GENIMAGES=discrete_linear_1D_convolution_alg1 discrete_linear_1D_convolution_alg
PAGES=$(subst .txt,.html,$(SOURCES))
PAGES+=$(subst .txt,.html,$(EXAMPLE_SOURCES))
-all: api.html examples.html $(PAGES) api_links.html
-
-#
-# Create all in one API page
-#
-api.html: $(SOURCES) api.txt
- asciidoc -a toc api.txt
+all: examples.html $(PAGES) api.html
#
# Create page for each part of API description
@@ -28,17 +22,9 @@ api.html: $(SOURCES) api.txt
$(PAGES): %.html: %.txt
asciidoc $<
-api_links.html: api_links.txt
- asciidoc $<
-
examples.html: examples.txt ../demos/c_simple/*.c ../demos/py_simple/*.py
asciidoc -a toc examples.txt
-api.pdf: api.txt
- asciidoc -b docbook api.txt
- xsltproc /usr/share/sgml/docbook/xsl-stylesheets/fo/docbook.xsl api.xml > api.fo
- fop api.fo -pdf api.pdf
-
#
# Clean up generated images
#
diff --git a/doc/README b/doc/README
index 87e78a6..ae93336 100644
--- a/doc/README
+++ b/doc/README
@@ -3,7 +3,3 @@ This directory contains asciidoc documentation.
The html pages are generated by typing 'make'.
In order to do that asciidoc and source-highlight, latex and dvipng must be installed.
-
-
-The pdf documentation could be generated by typing 'make api.pdf' for that fop
-and xsltproc must be installed.
diff --git a/doc/api.txt b/doc/api.txt
index 899df1c..aff68ea 100644
--- a/doc/api.txt
+++ b/doc/api.txt
@@ -2,17 +2,56 @@ GFXprim API
===========
Cyril Hrubis <metan(a)ucw.cz>
-This documentation is also available link:api_links.html[divided into several
-pages].
-
-include::general.txt[]
-include::basic_types.txt[]
-include::environment_variables.txt[]
-include::debug.txt[]
-include::context.txt[]
-include::gamma.txt[]
-include::drawing_api.txt[]
-include::filters.txt[]
-include::loaders.txt[]
-include::backends.txt[]
-include::grabbers.txt[]
+. link:basic_types.html[Basic library types]
+ +
+ Describes how colors and pixels are handled also describes progress callback
+ in great detail.
+ +
+. link:core.html[Library Core overview]
+ +
+ Describes functions and macros in library core.
+ +
+. link:debug.html[Debug Messages]
+ +
+ Interface to debug layer.
+ +
+. link:context.html[Context]
+ +
+ The Context is description of in-memory bitmap including some meta-data
+ (size, pixel format, etc...).
+ +
+. link:environment_variables.html[Environment Variables]
+ +
+ Description of environment variables that affects GFXprim behavior.
+ +
+. link:gamma.html[Gamma correction]
+ +
+ The gama correction description and handling in GFXprim.
+ +
+. link:drawing_api.html[Drawing primitives]
+ +
+ Drawing API for primitives such as lines, polygons and circles as well as
+ text drawing.
+ +
+. link:filters.html[Context filters]
+ +
+ Context filters, basically all algorithms that takes an Context as an input
+ and returns Context as output.
+ +
+ Includes resampling, convolutions, low pass (blur) filters, dithering and
+ more.
+ +
+. link:loaders.html[Context loaders]
+ +
+ Handles loading and saving images in standard formats.
+ +
+. link:backends.html[Backends]
+ +
+ Backends API for drawing on the screen or into a window.
+ +
+. link:grabbers.html[Grabbers]
+ +
+ Video grabbers interface such as V4L2.
+ +
+
+There is also a nice page with code link:examples.html[examples].
diff --git a/doc/api_links.txt b/doc/api_links.txt
deleted file mode 100644
index 3aff6f9..0000000
--- a/doc/api_links.txt
+++ /dev/null
@@ -1,60 +0,0 @@
-GFXprim API
-===========
-Cyril Hrubis <metan(a)ucw.cz>
-
-Also available in link:api.html[all in one page form].
-
-
-. link:basic_types.html[Basic library types]
- +
- Describes how colors and pixels are handled also describes progress callback
- in great detail.
- +
-. link:core.html[Library Core overview]
- +
- Describes functions and macros in library core.
- +
-. link:debug.html[Debug Messages]
- +
- Interface to debug layer.
- +
-. link:context.html[Context]
- +
- The Context is description of in-memory bitmap including some meta-data
- (size, pixel format, etc...).
- +
-. link:environment_variables.html[Environment Variables]
- +
- Description of environment variables that affects GFXprim behavior.
- +
-. link:gamma.html[Gamma correction]
- +
- The gama correction description and handling in GFXprim.
- +
-. link:drawing_api.html[Drawing primitives]
- +
- Drawing API for primitives such as lines, polygons and circles as well as
- text drawing.
- +
-. link:filters.html[Context filters]
- +
- Context filters, basically all algorithms that takes an Context as an input
- and returns Context as output.
- +
- Includes resampling, convolutions, low pass (blur) filters, dithering and
- more.
- +
-. link:loaders.html[Context loaders]
- +
- Handles loading and saving images in standard formats.
- +
-. link:backends.html[Backends]
- +
- Backends API for drawing on the screen or into a window.
- +
-. link:grabbers.html[Grabbers]
- +
- Video grabbers interface such as V4L2.
- +
-
-There is also a nice page with code link:examples.html[examples].
-----------------------------------------------------------------------
Summary of changes:
doc/Makefile | 18 +-----
doc/README | 4 -
doc/api.txt | 67 +++++++++++++++----
doc/api_links.txt | 60 -----------------
doc/backends.txt | 2 +
...loader_registration.txt => example_backend.txt} | 6 +-
doc/example_v4l2.txt | 17 +++++
doc/grabbers.txt | 2 +
8 files changed, 79 insertions(+), 97 deletions(-)
delete mode 100644 doc/api_links.txt
copy doc/{example_loader_registration.txt => example_backend.txt} (55%)
create mode 100644 doc/example_v4l2.txt
repo.or.cz automatic notification. Contact project admin jiri.bluebear.dluhos(a)gmail.com
if you want to unsubscribe, or site admin admin(a)repo.or.cz if you receive
no reply.
--
gfxprim.git ("A simple 2D graphics library with emphasis on correctness and well-defined operation.")
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 fd437dffad5c449ae3dff083562b0db30ea1eb8e (commit)
via b455c46c4d84d1ac66113db48722d9247cb2fc34 (commit)
via 03e092e8d75543e3446afe498e359bb1e4be6856 (commit)
via 03b001ae92a7ad29e60bcaa3ca1bb93e46963048 (commit)
from 80d1a231acdf63c758e84a257c20aaffca6550e3 (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/fd437dffad5c449ae3dff083562b0db30ea1…
commit fd437dffad5c449ae3dff083562b0db30ea1eb8e
Author: Cyril Hrubis <metan(a)ucw.cz>
Date: Sat Nov 10 16:49:36 2012 +0100
doc: Library core functions and macros docs.
diff --git a/doc/Makefile b/doc/Makefile
index acdade4..19b89d2 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -1,6 +1,6 @@
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
+ environment_variables.txt debug.txt core.txt
EXAMPLE_SOURCES=$(wildcard example_*.txt)
diff --git a/doc/api_links.txt b/doc/api_links.txt
index 2e41996..3aff6f9 100644
--- a/doc/api_links.txt
+++ b/doc/api_links.txt
@@ -10,6 +10,10 @@ Also available in link:api.html[all in one page form].
Describes how colors and pixels are handled also describes progress callback
in great detail.
+
+. link:core.html[Library Core overview]
+ +
+ Describes functions and macros in library core.
+ +
. link:debug.html[Debug Messages]
+
Interface to debug layer.
diff --git a/doc/core.txt b/doc/core.txt
new file mode 100644
index 0000000..fdb8056
--- /dev/null
+++ b/doc/core.txt
@@ -0,0 +1,140 @@
+Library 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.
+
+Common Macros and Inline Functions
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+[source,c]
+-------------------------------------------------------------------------------
+#include <core/GP_Common.h>
+/* or */
+#include <GP.h>
+
+GP_MIN(a, b);
+
+GP_MAX(a, b);
+
+GP_ABS(a);
+
+GP_SWAP(a, b);
+
+GP_SIGN(a);
+
+-------------------------------------------------------------------------------
+
+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.
+
+[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;
+}
+-------------------------------------------------------------------------------
+
http://repo.or.cz/w/gfxprim.git/commit/b455c46c4d84d1ac66113db48722d9247cb2…
commit b455c46c4d84d1ac66113db48722d9247cb2fc34
Author: Cyril Hrubis <metan(a)ucw.cz>
Date: Sat Nov 10 16:32:43 2012 +0100
doc: Update loaders documentation.
diff --git a/doc/Makefile b/doc/Makefile
index bda6964..acdade4 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -2,6 +2,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
+EXAMPLE_SOURCES=$(wildcard example_*.txt)
+
#
# Names of generated images for cleanup
#
@@ -10,7 +12,7 @@ GENIMAGES=discrete_linear_1D_convolution_alg1 discrete_linear_1D_convolution_alg
discrete_linear_convolution_alg2 laplacian_edge_sharpening laplacian_kernel
PAGES=$(subst .txt,.html,$(SOURCES))
-
+PAGES+=$(subst .txt,.html,$(EXAMPLE_SOURCES))
all: api.html examples.html $(PAGES) api_links.html
diff --git a/doc/example_loader_registration.txt b/doc/example_loader_registration.txt
new file mode 100644
index 0000000..b287560
--- /dev/null
+++ b/doc/example_loader_registration.txt
@@ -0,0 +1,7 @@
+Image Loader Registration Example
+---------------------------------
+
+[source,c]
+------------------------------------------------------------------
+include::../demos/c_simple/loaders_register.c[]
+------------------------------------------------------------------
diff --git a/doc/loaders.txt b/doc/loaders.txt
index 99ed35d..e12c6f8 100644
--- a/doc/loaders.txt
+++ b/doc/loaders.txt
@@ -3,14 +3,25 @@ Context loaders
This part of GFXprim library aims to create API to load and save images
from/to common image file formats.
+Currently we support JPEG, PNG and some PNM images for loading and saving and
+BMP, GIF and PSP for loading.
+
+Loaders API
+~~~~~~~~~~~
+
All loading functions returns a pointer to allocated and loaded image or upon
-a failure 'NULL' and 'errno' is set.
+a failure 'NULL'.
+
+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.
-All saving functions returns zero on success and non-zero on failure and
-'errno' is set. If image saving is aborted by a callback, the opened file is
-closed and removed from a filesystem before the call returns.
+The signature matching functions takes a 32 bytes long buffer and looks for a
+valid image signature. If signature is found 1 is returned.
-The possible 'errno' values (for both loading and saving) are:
+The possible 'errno' values are:
* anything returned by +open()+, +close()+, +lseek()+, +read()+, +write()+, ...
- 'ENOENT' if file doesn't exist
@@ -22,8 +33,11 @@ The possible 'errno' values (for both loading and saving) are:
* 'EIO' invalid image data (wrong signature, header or image data)
* 'ECANCELED' action canceled by returning non-zero from within a callback
-Common Loader
-~~~~~~~~~~~~~
+You can get more information about the error condition by turning on GFXprim
+debug messages.
+
+Image Loader
+~~~~~~~~~~~~
[source,c]
-------------------------------------------------------------------------------
@@ -34,9 +48,21 @@ Common Loader
GP_Context *GP_LoadImage(const char *src_path, GP_ProgressCallback *callback);
-------------------------------------------------------------------------------
-Loads image from a file. The format is now matched by an image file extension.
-Fallback to file signature if file content doesn't match it's extension is on
-the TODO.
+Loads image from a file.
+
+The image format is first guessed by the file extension. If loader for the
+file extension is found it's called and if it succedes the image data is
+returned.
+
+If extension based guess fails either because the extension wasn't matched or
+if the loader for the extension failed; the signature based method is used.
+The loader loads several bytes (currently 32) from the file and calls
+signature matching functions for each format that implements signature
+matching. If image signature is found particular image loader it is called
+and the result is returned.
+
+If file extension disagrees with file signature a warning is printed into the
+stdout.
[source,c]
-------------------------------------------------------------------------------
@@ -48,16 +74,115 @@ int GP_SaveImage(GP_Context *src, const char *dst_path,
GP_ProgressCallback *callback);
-------------------------------------------------------------------------------
-Saves a context into a file. The file format is matched accordingly to the
-file extension, if extension is invalid or if support for requested image
-format wasn't compiled in, non-zero is returned and 'errno' is set to
-'ENOSYS'.
+Saves a context into a file.
+
+The file format is matched accordingly to the file extension. If extension is
+not found non-zero is returned and 'errno' is set to 'EINVAL'. If extension
+was found but support for saving the image format is not implemented 'errno'
+is set to 'ENOSYS'.
+
+
+Advanced usage
+^^^^^^^^^^^^^^
+
+[source,c]
+-------------------------------------------------------------------------------
+typedef struct GP_Loader {
+ /*
+ * Loads an image.
+ *
+ * Returns allocated and initialized bitmap on success, NULL on failure
+ * and errno must be set.
+ */
+ GP_Context *(*Load)(const char *src_path, GP_ProgressCallback *callback);
+
+ /*
+ * Save an image.
+ *
+ * Returns zero on succes, non-zero on failure and errno must be set.
+ */
+ int (*Save)(const GP_Context *src, const char *dst_path,
+ GP_ProgressCallback *callback);
+
+ /*
+ * The buffer is filled with 32 bytes from an image start, returns 1 if
+ * image signature was found zero otherwise.
+ */
+ int (*Match)(const void *buf);
+
+ /*
+ * Short format name.
+ */
+ const char *fmt_name;
+
+ /* don't touch */
+ struct GP_Loader *next;
+
+ /*
+ * NULL terminated array of file extensions.
+ */
+ const char *extensions[];
+} GP_Loader;
+
+/*
+ * List loaders into the stdout.
+ */
+void GP_ListLoaders(void);
+
+/*
+ * Register a loader.
+ */
+void GP_LoaderRegister(GP_Loader *self);
+
+/*
+ * Unregister loader.
+ */
+void GP_LoaderUnregister(GP_Loader *self);
+-------------------------------------------------------------------------------
+
+The 'GP_Loader' structure describes an image loader.
+
+The 'Load', 'Save' and 'Match' functions could be 'NULL' if the particular
+functionality is not implemented.
+
+The 'fmt_name' is a short string that describes the format. For example:
+'Netbpm portable pixmap'.
+
+The extensions is 'NULL'-terminated array of strings that holds all possible
+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
+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.
+
+For example usage see image loader registration
+link:example_loader_registration.html[example].
+
+[source,c]
+-------------------------------------------------------------------------------
+#include <loaders/GP_Loaders.h>
+/* or */
+#include <GP.h>
+
+const GP_Loader *GP_MatchSignature(const void *buf)
+-------------------------------------------------------------------------------
+
+Returns pointer to image loader accordingly to image signature or 'NULL' if no
+suitable loader was found. The buf pointer must point to a buffer at least 32
+bytes long.
+
+WARNING: If you attempt to modify the content of the strucutre the behavior is
+ undefined. Most likely the program will crash.
-PNG
-~~~
+PNG Loader
+~~~~~~~~~~
The 'PNG' image support is implemented by the libpng library.
-WARNING: PNG images with alpha channel are not supported yet.
+NOTE: PNG images with alpha channel are not supported yet.
[source,c]
-------------------------------------------------------------------------------
@@ -114,8 +239,19 @@ Currently only 'RGB888' format is supported, you should convert the
'GP_Context' to 'RGB888' before calling this function otherwise non-zero is
returned and 'errno' is set to 'ENOSYS'.
-JPEG
-~~~~
+[source,c]
+-------------------------------------------------------------------------------
+#include <loaders/GP_PNG.h>
+/* or */
+#include <GP.h>
+
+int GP_MatchPNG(const void *buf);
+-------------------------------------------------------------------------------
+
+Matches a PNG signature.
+
+JPEG Loader
+~~~~~~~~~~~
The 'JPEG' image support is implemented by the jpeg library.
[source,c]
@@ -180,8 +316,19 @@ is closed and removed before the call returns non-zero and 'errno' is set to
The 'JPG' format could store either 'G8' or 'RGB888' pixeltypes and you must
convert the context into one of them before this functions is called.
-GIF
-~~~
+[source,c]
+-------------------------------------------------------------------------------
+#include <loaders/GP_JPG.h>
+/* or */
+#include <GP.h>
+
+int GP_MatchJPG(const void *buf);
+-------------------------------------------------------------------------------
+
+Matches a JPG signature.
+
+GIF Loader
+~~~~~~~~~~
The 'GIF' image support is implemented by the giflib library.
@@ -229,8 +376,19 @@ GP_Context *GP_LoadGIF(const char *src_path, GP_ProgressCallback *callback);
Same as above but takes path to the file as a parameter and check for the
signature. Basically this combines both of the calls above.
-BMP
-~~~
+[source,c]
+-------------------------------------------------------------------------------
+#include <loaders/GP_GIF.h>
+/* or */
+#include <GP.h>
+
+int GP_MatchGIF(const void *buf);
+-------------------------------------------------------------------------------
+
+Matches a GIF signature.
+
+BMP Loader
+~~~~~~~~~~
The 'BMP' loading support is nearly complete the only missing features should
be fancy RGB compressions and RLE support.
@@ -280,9 +438,72 @@ GP_Context *GP_LoadBMP(const char *src_path, GP_ProgressCallback *callback);
Same as above but takes path to the file as a parameter and check for the
signature. Basically this combines both of the calls above.
+
+[source,c]
+-------------------------------------------------------------------------------
+#include <loaders/GP_BMP.h>
+/* or */
+#include <GP.h>
+
+int GP_MatchBMP(const void *buf);
+-------------------------------------------------------------------------------
+
+Matches a BMP signature.
+
+PSP Loader
+~~~~~~~~~~
+
+The 'PSP' loader can load a composite image from a Paint Shop Pro Image Files.
+
+[source,c]
+-------------------------------------------------------------------------------
+#include <loaders/GP_PSP.h>
+/* or */
+#include <GP.h>
+
+int GP_OpenPSP(const char *src_path, FILE **f);
+-------------------------------------------------------------------------------
+
+Opens file and checks for 'PSP' signature. Upon successful return (file could
+be opened, signature matches) zero is returned. Upon failure non-zero is
+returned and 'errno' is set.
+
+[source,c]
+-------------------------------------------------------------------------------
+#include <loaders/GP_PSP.h>
+/* or */
+#include <GP.h>
+
+GP_Context *GP_ReadPSP(FILE *f, GP_ProgressCallback *callback);
+-------------------------------------------------------------------------------
+
+Reads 'PSP' image into a context.
+
+[source,c]
+-------------------------------------------------------------------------------
+#include <loaders/GP_PSP.h>
+/* or */
+#include <GP.h>
+
+GP_Context *GP_LoadPSP(const char *src_path, GP_ProgressCallback *callback);
+-------------------------------------------------------------------------------
+
+Same as above but takes path to the file as a parameter and check for the
+signature. Basically this combines both of the calls above.
+
+[source,c]
+-------------------------------------------------------------------------------
+#include <loaders/GP_PSP.h>
+/* or */
+#include <GP.h>
+
+int GP_MatchPSP(const void *buf);
+-------------------------------------------------------------------------------
+
+Matches a PSP signature.
+
PBM, PGM, PPM
~~~~~~~~~~~~~
There is a code do load and write 'PBM', 'PGM' and 'PPM' images too. However
it's not finished and its API is outdated. Use at your own risk.
-
http://repo.or.cz/w/gfxprim.git/commit/03e092e8d75543e3446afe498e359bb1e4be…
commit 03e092e8d75543e3446afe498e359bb1e4be6856
Author: Cyril Hrubis <metan(a)ucw.cz>
Date: Sat Nov 10 15:07:30 2012 +0100
loaders: Add GP_MatchImage().
diff --git a/include/loaders/GP_Loader.h b/include/loaders/GP_Loader.h
index ef7add1..6730613 100644
--- a/include/loaders/GP_Loader.h
+++ b/include/loaders/GP_Loader.h
@@ -102,6 +102,12 @@ typedef struct GP_Loader {
const char *extensions[];
} GP_Loader;
+/*
+ * Takes pointer to buffer at least 32 bytes long and returns a pointer to
+ * matched loader or NULL.
+ */
+const GP_Loader *GP_MatchSignature(const void *buf);
+
void GP_LoaderRegister(GP_Loader *self);
void GP_LoaderUnregister(GP_Loader *self);
diff --git a/libs/loaders/GP_Loader.c b/libs/loaders/GP_Loader.c
index b1769be..3d626a6 100644
--- a/libs/loaders/GP_Loader.c
+++ b/libs/loaders/GP_Loader.c
@@ -199,13 +199,13 @@ static struct GP_Loader *loader_by_filename(const char *path)
return loader_by_extension(ext);
}
-static struct GP_Loader *loader_by_signature(const char *path)
+static const GP_Loader *loader_by_signature(const char *path)
{
uint8_t buf[32];
FILE *f;
int err;
- GP_DEBUG(1, "Trying to match file signature");
+ GP_DEBUG(1, "Trying to load a file by signature");
f = fopen(path, "rb");
@@ -224,16 +224,7 @@ static struct GP_Loader *loader_by_signature(const char *path)
fclose(f);
- struct GP_Loader *i;
-
- for (i = loaders; i != NULL; i = i->next) {
- if (i->Match && i->Match(buf)) {
- GP_DEBUG(1, "Found loader '%s'", i->fmt_name);
- return i;
- }
- }
-
- return NULL;
+ return GP_MatchSignature(buf);
}
GP_Context *GP_LoadImage(const char *src_path, GP_ProgressCallback *callback)
@@ -253,7 +244,7 @@ GP_Context *GP_LoadImage(const char *src_path, GP_ProgressCallback *callback)
}
GP_Context *img;
- struct GP_Loader *ext_load = NULL, *sig_load;
+ const GP_Loader *ext_load = NULL, *sig_load;
ext_load = loader_by_filename(src_path);
@@ -431,3 +422,19 @@ int GP_SaveImage(const GP_Context *src, const char *dst_path,
errno = ENOSYS;
return 1;
}
+
+const GP_Loader *GP_MatchSignature(const void *buf)
+{
+ struct GP_Loader *i;
+
+ for (i = loaders; i != NULL; i = i->next) {
+ if (i->Match && i->Match(buf) == 1) {
+ GP_DEBUG(1, "Found loader '%s'", i->fmt_name);
+ return i;
+ }
+ }
+
+ GP_DEBUG(1, "Loader not found");
+
+ return NULL;
+}
http://repo.or.cz/w/gfxprim.git/commit/03b001ae92a7ad29e60bcaa3ca1bb93e4696…
commit 03b001ae92a7ad29e60bcaa3ca1bb93e46963048
Author: Cyril Hrubis <metan(a)ucw.cz>
Date: Sat Nov 10 14:39:44 2012 +0100
loaders: Now we aren't fooled by wrong filename extension.
diff --git a/libs/loaders/GP_Loader.c b/libs/loaders/GP_Loader.c
index 0ef1024..b1769be 100644
--- a/libs/loaders/GP_Loader.c
+++ b/libs/loaders/GP_Loader.c
@@ -236,6 +236,48 @@ static struct GP_Loader *loader_by_signature(const char *path)
return NULL;
}
+GP_Context *GP_LoadImage(const char *src_path, GP_ProgressCallback *callback)
+{
+ int saved_errno;
+
+ if (access(src_path, R_OK)) {
+
+ saved_errno = errno;
+
+ GP_DEBUG(1, "Failed to access file '%s' : %s",
+ src_path, strerror(errno));
+
+ errno = saved_errno;
+
+ return NULL;
+ }
+
+ GP_Context *img;
+ struct GP_Loader *ext_load = NULL, *sig_load;
+
+ ext_load = loader_by_filename(src_path);
+
+ if (ext_load != NULL) {
+ img = ext_load->Load(src_path, callback);
+
+ if (img)
+ return img;
+ }
+
+ sig_load = loader_by_signature(src_path);
+
+ if (ext_load && sig_load) {
+ GP_WARN("File '%s': Extension says %s but signature %s",
+ src_path, ext_load->fmt_name, sig_load->fmt_name);
+ }
+
+ if (sig_load)
+ return sig_load->Load(src_path, callback);
+
+ errno = ENOSYS;
+ return NULL;
+}
+
enum GP_ImageFmt {
GP_FMT_UNKNOWN,
GP_FMT_PNG,
@@ -341,61 +383,6 @@ enum GP_ImageFmt filename_to_fmt(const char *path)
return GP_FMT_UNKNOWN;
}
-GP_Context *GP_LoadImage(const char *src_path, GP_ProgressCallback *callback)
-{
- int saved_errno;
-
- if (access(src_path, R_OK)) {
-
- saved_errno = errno;
-
- GP_DEBUG(1, "Failed to access file '%s' : %s",
- src_path, strerror(errno));
-
- errno = saved_errno;
-
- return NULL;
- }
-
- enum GP_ImageFmt fmt = filename_to_fmt(src_path);
-
- switch (fmt) {
- case GP_FMT_JPG:
- return GP_LoadJPG(src_path, callback);
- case GP_FMT_PNG:
- return GP_LoadPNG(src_path, callback);
- case GP_FMT_GIF:
- return GP_LoadGIF(src_path, callback);
- case GP_FMT_PSP:
- return GP_LoadPSP(src_path, callback);
- case GP_FMT_BMP:
- return GP_LoadBMP(src_path, callback);
- case GP_FMT_PBM:
- return GP_LoadPBM(src_path, callback);
- case GP_FMT_PGM:
- return GP_LoadPGM(src_path, callback);
- case GP_FMT_PPM:
- return GP_LoadPPM(src_path, callback);
- case GP_FMT_UNKNOWN:
- break;
- }
-
- struct GP_Loader *l;
-
- l = loader_by_filename(src_path);
-
- if (l != NULL)
- return l->Load(src_path, callback);
-
- l = loader_by_signature(src_path);
-
- if (l != NULL)
- return l->Load(src_path, callback);
-
- errno = ENOSYS;
- return NULL;
-}
-
int GP_LoadMetaData(const char *src_path, GP_MetaData *data)
{
int saved_errno;
-----------------------------------------------------------------------
Summary of changes:
doc/Makefile | 6 +-
doc/api_links.txt | 4 +
doc/core.txt | 140 ++++++++++++++++++
doc/example_loader_registration.txt | 7 +
doc/loaders.txt | 269 +++++++++++++++++++++++++++++++---
include/loaders/GP_Loader.h | 6 +
libs/loaders/GP_Loader.c | 120 ++++++++--------
7 files changed, 463 insertions(+), 89 deletions(-)
create mode 100644 doc/core.txt
create mode 100644 doc/example_loader_registration.txt
repo.or.cz automatic notification. Contact project admin jiri.bluebear.dluhos(a)gmail.com
if you want to unsubscribe, or site admin admin(a)repo.or.cz if you receive
no reply.
--
gfxprim.git ("A simple 2D graphics library with emphasis on correctness and well-defined operation.")
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 6793b01905a9072059080e70fa79c685e43a945c (commit)
from 156709b6343ea54485a3d662ddc66448e3337c76 (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/6793b01905a9072059080e70fa79c685e43a…
commit 6793b01905a9072059080e70fa79c685e43a945c
Author: Cyril Hrubis <metan(a)ucw.cz>
Date: Tue Nov 6 19:54:09 2012 +0100
loaders: Add forgotten header, ouch.
I will not forgot to add the headers.
I will not forgot to add the headers.
I will not forgot to add the headers.
I will not forgot to add the headers.
diff --git a/include/loaders/GP_Loader.h b/include/loaders/GP_Loader.h
new file mode 100644
index 0000000..a5ef06b
--- /dev/null
+++ b/include/loaders/GP_Loader.h
@@ -0,0 +1,109 @@
+/*****************************************************************************
+ * This file is part of gfxprim library. *
+ * *
+ * Gfxprim is free software; you can redistribute it and/or *
+ * modify it under the terms of the GNU Lesser General Public *
+ * License as published by the Free Software Foundation; either *
+ * version 2.1 of the License, or (at your option) any later version. *
+ * *
+ * Gfxprim is distributed in the hope that it will be useful, *
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of *
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU *
+ * Lesser General Public License for more details. *
+ * *
+ * You should have received a copy of the GNU Lesser General Public *
+ * License along with gfxprim; if not, write to the Free Software *
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, *
+ * Boston, MA 02110-1301 USA *
+ * *
+ * Copyright (C) 2009-2012 Cyril Hrubis <metan(a)ucw.cz> *
+ * *
+ *****************************************************************************/
+
+ /*
+
+ Core include file for loaders API.
+
+ */
+
+#ifndef LOADERS_GP_LOADER_H
+#define LOADERS_GP_LOADER_H
+
+#include "core/GP_Context.h"
+#include "core/GP_ProgressCallback.h"
+
+#include "GP_MetaData.h"
+
+/*
+ * Tries to load image accordingly to the file extension.
+ *
+ * If operation fails NULL is returned and errno is filled.
+ */
+GP_Context *GP_LoadImage(const char *src_path, GP_ProgressCallback *callback);
+
+/*
+ * Loads image Meta Data (if possible).
+ */
+int GP_LoadMetaData(const char *src_path, GP_MetaData *data);
+
+/*
+ * Simple saving function, the image format is matched by file extension.
+ *
+ * Retruns zero on succes.
+ *
+ * On failure non-zero is returned.
+ *
+ * When file type wasn't recognized by extension or if support for requested
+ * image format wasn't compiled in non-zero is returned and errno is set to
+ * ENOSYS.
+ *
+ * The resulting errno may also be set to any possible error from fopen(3), open(3),
+ * write(3), fwrite(3), seek(3), etc..
+ */
+int GP_SaveImage(const GP_Context *src, const char *dst_path,
+ GP_ProgressCallback *callback);
+
+/*
+ * You can register your own loader here.
+ */
+typedef struct GP_Loader {
+ /*
+ * Loads an image.
+ *
+ * Returns allocated and initialized bitmap on success, NULL on failure
+ * and errno must be set.
+ */
+ GP_Context *(*Load)(const char *src_path, GP_ProgressCallback *callback);
+
+ /*
+ * Save an image.
+ *
+ * Returns zero on succes, non-zero on failure and errno must be set.
+ */
+ int (*Save)(const GP_Context *src, const char *dst_path, GP_ProgressCallback *callback);
+
+ /*
+ * The buffer is filled with 32 bytes from an image start, returns 1 if
+ * image signature was found zero otherwise.
+ */
+ int (*Match)(const void *buf);
+
+ /*
+ * Short format name.
+ */
+ const char *fmt_name;
+
+ /* don't touch */
+ struct GP_Loader *next;
+
+ /*
+ * NULL terminated array of file extensions.
+ */
+ const char *extensions[];
+} GP_Loader;
+
+void GP_LoaderRegister(GP_Loader *self);
+
+void GP_LoaderUnregister(GP_Loader *self);
+
+#endif /* LOADERS_GP_LOADER_H */
-----------------------------------------------------------------------
Summary of changes:
include/loaders/GP_Loader.h | 109 +++++++++++++++++++++++++++++++++++++++++++
1 files changed, 109 insertions(+), 0 deletions(-)
create mode 100644 include/loaders/GP_Loader.h
repo.or.cz automatic notification. Contact project admin jiri.bluebear.dluhos(a)gmail.com
if you want to unsubscribe, or site admin admin(a)repo.or.cz if you receive
no reply.
--
gfxprim.git ("A simple 2D graphics library with emphasis on correctness and well-defined operation.")