Commit 32abeb4c authored by Owen Taylor's avatar Owen Taylor Committed by Owen Taylor
Browse files

Use the new snazzy mother-of-all-gtk-doc-makefiles.

Sun Feb 11 22:16:34 2001  Owen Taylor  <otaylor@redhat.com>

	* */Makefile.am: Use the new snazzy mother-of-all-gtk-doc-makefiles.

	* gdk/tmpl/* gdk-pixbuf/tmpl/*: Recover a bunch of docs that were
	lost at one point.
parent 730a2bdc
Sun Feb 11 22:16:34 2001 Owen Taylor <otaylor@redhat.com>
* */Makefile.am: Use the new snazzy mother-of-all-gtk-doc-makefiles.
* gdk/tmpl/* gdk-pixbuf/tmpl/*: Recover a bunch of docs that were
lost at one point.
2001-02-08 Havoc Pennington <hp@pobox.com>
* gtk/windows.sgml: windows (file is blank)
......
......@@ -6,40 +6,34 @@ DOC_MODULE=gdk-pixbuf
# The top-level SGML file.
DOC_MAIN_SGML_FILE=gdk-pixbuf.sgml
# The directory containing the source code (if it contains documentation).
DOC_SOURCE_DIR=$(GDK_PIXBUF_DIR)/gdk-pixbuf
SECOND_DOC_SOURCE_DIR=$(top_srcdir)/contrib/gdk-pixbuf-xlib
# The directory containing the source code. Relative to $(srcdir)
DOC_SOURCE_DIR=../../../gdk-pixbuf
# Extra options to supply to gtkdoc-scan
SCAN_OPTIONS=--source-dir=../../../contrib/gdk-pixbuf-xlib
# Extra options to supply to gtkdoc-mkdb
MKDB_OPTIONS=--source-dir=../../../contrib/gdk-pixbuf-xlib
# Extra options to supply to gtkdoc-fixref
FIXXREF_OPTIONS=
# Used for dependencies
HFILE_GLOB=$(top_srcdir)/gdk-pixbuf/*.h $(top_srcdir)/contrib/gdk-pixbuf-xlib/*.h
CFILE_GLOB=$(top_srcdir)/gdk-pixbuf/*.c $(top_srcdir)/contrib/gdk-pixbuf-xlib/*.c
# Header files to ignore when scanning
IGNORE_HFILES=pixops.h pixops-internal.h gdk-pixbuf-xlib-private.h gdk-pixbuf-i18n.h gdk-pixbuf-private.h
IGNORE_HFILES= \
pixops \
gdk-pixbuf-xlib-private.h \
gdk-pixbuf-i18n.h \
gdk-pixbuf-private.h
# Extra files to add when scanning
EXTRA_HFILES= \
$(top_srcdir)/gtk/gdk-pixbuf-loader.h
# CFLAGS and LDFLAGS for compiling scan program
CFLAGS=
LDFLAGS=
tmpl_sources = \
tmpl/animation.sgml \
tmpl/creating.sgml \
tmpl/file-loading.sgml \
tmpl/gdk-pixbuf-loader.sgml \
tmpl/gdk-pixbuf-unused.sgml \
tmpl/gdk-pixbuf.sgml \
tmpl/initialization_versions.sgml \
tmpl/module_interface.sgml \
tmpl/refcounting.sgml \
tmpl/scaling.sgml \
tmpl/util.sgml \
tmpl/gdk-pixbuf-xlib-from-drawables.sgml \
tmpl/gdk-pixbuf-xlib-init.sgml \
tmpl/gdk-pixbuf-xlib-rendering.sgml \
tmpl/gdk-pixbuf-xlib-rgb.sgml
EXTRA_HFILES=
# Images to copy into HTML directory
HTML_IMAGES =
# Extra SGML files that are included by DOC_MAIN_SGML_FILE
content_files = \
......@@ -47,6 +41,30 @@ content_files = \
gdk-pixbuf.sgml \
porting-from-imlib.sgml
# Other files to distribute
extra_files =
# CFLAGS and LDFLAGS for compiling scan program. Only needed
# if $(DOC_MODULE).types is non-empty.
GTKDOC_CFLAGS = @STRIP_BEGIN@ \
@CFLAGS@ \
-I$(top_srcdir) \
@GLIB_CFLAGS@ \
@more_cflags@ \
@STRIP_END@
GTKDOC_LIBS = @STRIP_BEGIN@ \
$(top_builddir)/gdk-pixbuf/libgdk_pixbuf-1.3.la \
@more_ldflags@ \
@more_libs@ \
@GLIB_LIBS@ \
-lm \
@STRIP_END@
GTKDOC_CC=$(LIBTOOL) --mode=compile $(CC)
GTKDOC_LD=$(LIBTOOL) --mode=link $(CC)
####################################
# Everything below here is generic #
####################################
......@@ -54,47 +72,76 @@ content_files = \
TARGET_DIR=$(HTML_DIR)/$(DOC_MODULE)
EXTRA_DIST = \
$(DOC_MODULE).types \
$(DOC_MAIN_SGML_FILE) \
$(content_files) \
$(extra_files) \
$(HTML_IMAGES) \
$(DOC_MAIN_SGML_FILE) \
$(DOC_MODULE).types \
$(DOC_MODULE)-sections.txt \
$(DOC_MODULE)-overrides.txt
DOC_STAMPS=scan-build.stamp tmpl-build.stamp sgml-build.stamp html-build.stamp
if ENABLE_GTK_DOC
all-local: html/index.html
all-local: html-build.stamp
SCANOBJ_FILES = \
$(DOC_MODULE).args \
$(DOC_MODULE).hierarchy \
$(DOC_MODULE).signal
scan-build.stamp: $(HFILE_GLOB)
@echo '*** Scanning header files ***'
cd $(srcdir) && ( \
if grep -l '^.+$$' $(DOC_MODULE).types > /dev/null ; then \
CC="$(GTKDOC_CC)" LD="$(GTKDOC_LD)" CFLAGS="$(GTKDOC_CFLAGS)" LDFLAGS="$(GTKDOC_LIBS)" gtkdoc-scangobj --module=$(DOC_MODULE) ; \
else \
for i in $(SCANOBJ_FILES) ; do \
test -f $$i || touch $$i ; \
done \
fi )
cd $(srcdir) && \
gtkdoc-scan --module=$(DOC_MODULE) --source-dir=$(DOC_SOURCE_DIR) --ignore-headers="$(IGNORE_HFILES)" $(SCAN_OPTIONS) $(EXTRA_HFILES)
touch scan-build.stamp
check_scan:
$(MAKE) scan-build.stamp
$(DOC_MODULE)-decl.txt:
$(MAKE) scan
$(DOC_MODULE)-decl.txt $(SCANOBJ_FILES): check_scan
$(tmpl_sources): $(DOC_MODULE)-decl.txt $(DOC_MODULE)-sections.txt $(DOC_MODULE)-overrides.txt
$(MAKE) templates
tmpl-build.stamp: $(DOC_MODULE)-decl.txt $(SCANOBJ_FILES) $(DOC_MODULE)-sections.txt $(DOC_MODULE)-overrides.txt
@echo '*** Rebuilding template files ***'
cd $(srcdir) && gtkdoc-mktmpl --module=$(DOC_MODULE)
touch tmpl-build.stamp
sgml/$(DOC_MODULE)-doc.bottom: $(tmpl_sources) $(DOC_MODULE)-decl.txt
$(MAKE) sgml
check_templates:
$(MAKE) tmpl-build.stamp
html/index.html: sgml/$(DOC_MODULE)-doc.bottom $(DOC_MAIN_SGML_FILE) $(content_files)
$(MAKE) html
endif
tmpl.stamp: check_templates
scan:
-(cd $(srcdir) \
&& gtkdoc-scan --module=$(DOC_MODULE) --source-dir=$(DOC_SOURCE_DIR) --source-dir=$(SECOND_DOC_SOURCE_DIR) --ignore-headers="$(IGNORE_HFILES)" $(EXTRA_HFILES))
sgml-build.stamp: tmpl.stamp $(CFILE_GLOB)
@echo '*** Building SGML ***'
cd $(srcdir) && \
gtkdoc-mkdb --module=$(DOC_MODULE) --source-dir=$(DOC_SOURCE_DIR) $(MKDB_OPTIONS)
touch sgml-build.stamp
templates:
cd $(srcdir) && gtkdoc-mktmpl --module=$(DOC_MODULE)
check_sgml:
$(MAKE) sgml-build.stamp
sgml:
cd $(srcdir) \
&& gtkdoc-mkdb --module=$(DOC_MODULE) --source-dir=$(DOC_SOURCE_DIR) --source-dir=$(SECOND_DOC_SOURCE_DIR)
sgml.stamp: check_sgml
html:
html-build.stamp: sgml.stamp $(DOC_MAIN_SGML_FILE)
@echo '*** Building HTML ***'
test -d $(srcdir)/html || mkdir $(srcdir)/html
-cd $(srcdir)/html && gtkdoc-mkhtml $(DOC_MODULE) ../$(DOC_MAIN_SGML_FILE)
cd $(srcdir)/html && gtkdoc-mkhtml $(DOC_MODULE) ../$(DOC_MAIN_SGML_FILE)
test "x$(HTML_IMAGES)" = "x" || ( cd $(srcdir) && cp $(HTML_IMAGES) html )
@echo '-- Fixing Crossreferences'
cd $(srcdir) && gtkdoc-fixxref --module-dir=html --html-dir=$(HTML_DIR) $(FIXXREF_OPTIONS)
touch html-build.stamp
endif
clean-local:
rm -f *~ *.bak *.signals *-unused.txt
rm -f *~ *.bak $(SCANOBJ_FILES) *-unused.txt $(DOC_STAMPS) $(srcdir)/sgml.stamp
maintainer-clean-local: clean
cd $(srcdir) && rm -rf sgml html $(DOC_MODULE)-decl-list.txt $(DOC_MODULE)-decl.txt
......@@ -120,17 +167,22 @@ if ENABLE_GTK_DOC
dist-check-gtkdoc:
else
dist-check-gtkdoc:
@echo "*** gtk-doc must be installed and enabled in order to make dist
@echo "*** gtk-doc must be installed and enabled in order to make dist"
@false
endif
dist-hook: dist-check-gtkdoc
mkdir $(distdir)/html
mkdir $(distdir)/sgml
dist-hook: dist-check-gtkdoc dist-hook-local
mkdir $(distdir)/tmpl
-cp $(srcdir)/html/*.html $(srcdir)/html/*.css $(srcdir)/html/index.sgml $(distdir)/html
mkdir $(distdir)/sgml
mkdir $(distdir)/html
-cp $(srcdir)/tmpl/*.sgml $(distdir)/tmpl
-cp $(srcdir)/sgml/*.sgml $(distdir)/sgml
-cp $(srcdir)/sgml/*.bottom $(srcdir)/sgml/*.top $(distdir)/sgml
-cp $(srcdir)/html/index.sgml $(distdir)/html
-cp $(srcdir)/html/*.html $(srcdir)/html/*.css $(distdir)/html
for i in $(HTML_IMAGES) ; do \
cp $(srcdir)/$$i $(distdir)/html ; \
done
.PHONY : check_sgml check_templates check_scan dist-hook-local
.PHONY : html sgml templates scan
<!-- ##### SECTION Title ##### -->
animation
Animations
<!-- ##### SECTION Short_Description ##### -->
Animations as multi-frame structures.
<!-- ##### SECTION Long_Description ##### -->
<para>
</para>
<para>
The &gdk-pixbuf; library provides a simple mechanism to load and
represent animations, primarily animated GIF files. Animations
are represented as lists of #GdkPixbufFrame structures. Each
frame structure contains a #GdkPixbuf structure and information
about the frame's overlay mode and duration.
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
</para>
<para>
#GdkPixbufLoader
</para>
<!-- ##### ENUM GdkPixbufFrameAction ##### -->
<para>
</para>
@GDK_PIXBUF_FRAME_RETAIN:
@GDK_PIXBUF_FRAME_DISPOSE:
@GDK_PIXBUF_FRAME_REVERT:
<para>
Each animation frame can have several things happen to it when the
next frame is displayed. The #GdkPixbufFrameAction determines
this. These are essentially the overlay modes supported by GIF
animations.
</para>
@GDK_PIXBUF_FRAME_RETAIN: The previous image should remain displayed,
and will potentially be occluded by the new frame.
@GDK_PIXBUF_FRAME_DISPOSE: The animation will be reverted to the state
before the frame was shown.
@GDK_PIXBUF_FRAME_REVERT: The animation will be reverted to the first
frame.
<!-- ##### STRUCT GdkPixbufFrame ##### -->
<para>
</para>
<para>
This structure describes a frame in a #GdkPixbufAnimation. Each
frame consists of a #GdkPixbuf, an offset of the frame within the
animation's bounding box, a duration, and an overlay mode or
action.
</para>
<!-- ##### STRUCT GdkPixbufAnimation ##### -->
<para>
</para>
<para>
This structure describes an animation, which is represented as a
list of #GdkPixbufFrame structures.
</para>
<!-- ##### FUNCTION gdk_pixbuf_animation_new_from_file ##### -->
......@@ -140,6 +154,11 @@ animation
</para>
@frame:
@Returns:
@Returns: <!--
Local variables:
mode: sgml
sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
End:
-->
<!-- ##### SECTION Title ##### -->
creating
Image Data in Memory
<!-- ##### SECTION Short_Description ##### -->
Creating a pixbuf from image data that is already in memory.
<!-- ##### SECTION Long_Description ##### -->
<para>
</para>
<para>
The most basic way to create a pixbuf is to wrap an existing pixel
buffer with a #GdkPixbuf structure. You can use the
gdk_pixbuf_new_from_data() function to do this You need to specify
the destroy notification function that will be called when the
data buffer needs to be freed; this will happen when a #GdkPixbuf
is finalized by the reference counting functions If you have a
chunk of static data compiled into your application, you can pass
in #NULL as the destroy notification function so that the data
will not be freed.
</para>
<para>
The gdk_pixbuf_new() function can be used as a convenience to
create a pixbuf with an empty buffer. This is equivalent to
allocating a data buffer using malloc() and then wrapping it with
gdk_pixbuf_new_from_data(). The gdk_pixbuf_new() function will
compute an optimal rowstride so that rendering can be performed
with an efficient algorithm.
</para>
<para>
As a special case, you can use the gdk_pixbuf_new_from_xpm_data()
function to create a pixbuf from inline XPM image data.
</para>
<para>
You can also copy an existing pixbuf with the gdk_pixbuf_copy()
function. This is not the same as just doing a gdk_pixbuf_ref()
on the old pixbuf; the copy function will actually duplicate the
pixel data in memory and create a new #GdkPixbuf structure for it.
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
</para>
<para>
gdk_pixbuf_finalize().
</para>
<!-- ##### FUNCTION gdk_pixbuf_new ##### -->
<para>
......@@ -84,8 +113,11 @@ creating
</para>
@pixbuf:
@Returns:
<!-- # Unused Parameters # -->
@src:
@Returns: <!--
Local variables:
mode: sgml
sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
End:
-->
<!-- ##### SECTION Title ##### -->
file-loading
File Loading
<!-- ##### SECTION Short_Description ##### -->
Loading a pixbuf from a file.
<!-- ##### SECTION Long_Description ##### -->
<para>
</para>
<para>
The &gdk-pixbuf; library provides a simple mechanism for loading
an image from a file in synchronous fashion. This means that the
library takes control of the application while the file is being
loaded; from the user's point of view, the application will block
until the image is done loading.
</para>
<para>
This interface can be used by applications in which blocking is
acceptable while an image is being loaded. It can also be used to
load small images in general. Applications that need progressive
loading can use the #GdkPixbufLoader functionality instead.
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
</para>
<para>
#GdkPixbufLoader.
</para>
<!-- ##### FUNCTION gdk_pixbuf_new_from_file ##### -->
<para>
......@@ -21,6 +32,11 @@ file-loading
@filename:
@error:
@Returns:
@Returns: <!--
Local variables:
mode: sgml
sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
End:
-->
<!-- ##### SECTION Title ##### -->
gdk-pixbuf-xlib-init
&gdk-pixbuf; Xlib initialization
<!-- ##### SECTION Short_Description ##### -->
Initializing the &gdk-pixbuf; Xlib library.
<!-- ##### SECTION Long_Description ##### -->
<para>
</para>
<para>
In addition to the normal Gdk-specific functions, the &gdk-pixbuf;
package provides a small library that lets Xlib-only applications
use #GdkPixbuf structures and render them to X drawables. The
functions in this section are used to initialize the &gdk-pixbuf;
Xlib library. This library must be initialized near the beginning
or the program or before calling any of the other &gdk-pixbuf;
Xlib functions; it cannot be initialized automatically since
Xlib-only applications do not call gdk_rgb_init() like GNOME
applications do.
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
</para>
<para>
XlibRGB
</para>
<!-- ##### FUNCTION gdk_pixbuf_xlib_init ##### -->
<para>
......@@ -30,6 +38,11 @@ gdk-pixbuf-xlib-init
@display:
@screen_num:
@prefDepth:
@prefDepth: <!--
Local variables:
mode: sgml
sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
End:
-->
<!-- ##### SECTION Title ##### -->
gdk-pixbuf
The GdkPixbuf Structure
<!-- ##### SECTION Short_Description ##### -->
Information that describes an image.
<!-- ##### SECTION Long_Description ##### -->
<para>
</para>
<para>
The <structname>GdkPixbuf</structname> structure contains
information that describes an image in memory.
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
</para>
<para>
</para>
<!-- ##### ENUM GdkPixbufError ##### -->
<para>
......@@ -34,24 +35,39 @@ gdk-pixbuf
<!-- ##### ENUM GdkColorspace ##### -->
<para>
</para>
<para>
This enumeration defines the color spaces that are supported by
the &gdk-pixbuf; library. Currently only RGB is supported.
</para>
@GDK_COLORSPACE_RGB:
@GDK_COLORSPACE_RGB: Indicates a red/green/blue additive color space.
<!-- ##### ENUM GdkPixbufAlphaMode ##### -->
<para>
</para>
@GDK_PIXBUF_ALPHA_BILEVEL:
@GDK_PIXBUF_ALPHA_FULL:
<para>
These values can be passed to
gdk_pixbuf_render_to_drawable_alpha() to control how the alpha
chanel of an image should be handled. This function can create a
bilevel clipping mask (black and white) and use it while painting
the image. In the future, when the X Window System gets an alpha
channel extension, it will be possible to do full alpha
compositing onto arbitrary drawables. For now both cases fall
back to a bilevel clipping mask.
</para>
@GDK_PIXBUF_ALPHA_BILEVEL: A bilevel clipping mask (black and white)
will be created and used to draw the image. Pixels below 0.5 opacity
will be considered fully transparent, and all others will be
considered fully opaque.
@GDK_PIXBUF_ALPHA_FULL: For now falls back to #GDK_PIXBUF_ALPHA_BILEVEL.
In the future it will do full alpha compositing.
<!-- ##### STRUCT GdkPixbuf ##### -->
<para>
</para>
<para>
This is the main structure in the &gdk-pixbuf; library. It is
used to represent images. It contains information about the
image's pixel data, its color space, bits per sample, width and
height, and the rowstride or number of bytes between rows.
</para>
<!-- ##### FUNCTION gdk_pixbuf_get_colorspace ##### -->
......@@ -123,6 +139,11 @@ gdk-pixbuf
</para>
@pixbuf:
@Returns:
@Returns: <!--
Local variables:
mode: sgml
sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
End:
-->
......@@ -14,31 +14,6 @@ Initialization and Versions
</para>
<!-- ##### FUNCTION gdk_pixbuf_init ##### -->
<para>
</para>
<!-- ##### FUNCTION gdk_pixbuf_preinit ##### -->
<para>
</para>
@app:
@modinfo:
<!-- ##### FUNCTION gdk_pixbuf_postinit ##### -->
<para>
</para>
@app:
@modinfo:
<!-- ##### VARIABLE gdk_pixbuf_version ##### -->
<para>
......
<!-- ##### SECTION Title ##### -->
refcounting
Reference Counting and Memory Mangement
<!-- ##### SECTION Short_Description ##### -->
Functions to perform reference counting and memory management on a
#GdkPixbuf.