AuroraMiddleware/gtk
1
0
Fork 1
mirror of https://gitlab.gnome.org/GNOME/gtk.git synced 2025-01-12 05:20:17 +00:00
Code Issues Projects Releases Wiki Activity

More docs work - Federico

Browse Source
This commit is contained in:
Arturo Espinosa 1999-11-04 21:52:08 +00:00
parent 76f716cec7
commit 9d8da16ee9
17 changed files with 241 additions and 89 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
docs/reference/gdk-pixbuf/Makefile.am
View File

@ -16,15 +16,23 @@ HTML_DIR=$(datadir)/gnome/html
TARGET_DIR=$(HTML_DIR)/$(DOC_MODULE)
tmpl_sources = foo
tmpl_sources = \
tmpl/creating.sgml \
tmpl/file-loading.sgml \
tmpl/gdk-pixbuf-io.sgml \
tmpl/gdk-pixbuf-loader.sgml \
tmpl/gdk-pixbuf-unused.sgml \
tmpl/gdk-pixbuf.sgml \
tmpl/gnome-canvas-pixbuf.sgml \
tmpl/refcounting.sgml \
tmpl/rendering.sgml
gdk_pixbuf_docdir = $(HTML_DIR)
gdk_pixbuf_doc_DATA = \
gdk-pixbuf.html \
gdk-pixbuf.hierarchy \
gdk-pixbuf.types \
gdk-pixbuf-scan.c \
gdk-pixbuf-decl.txt \
gdk_pixbuf_doc_DATA = \
gdk-pixbuf.html \
gdk-pixbuf.hierarchy \
gdk-pixbuf.types \
gdk-pixbuf-decl.txt \
gdk-pixbuf-sections.txt
EXTRA_DIST = $(gdk_pixbuf_doc_DATA)

7
docs/reference/gdk-pixbuf/gdk-pixbuf-decl.txt
View File

@ -24,6 +24,11 @@ GdkPixbufCache *cache,const char *file
<RETURNS>void </RETURNS>
GdkPixbuf *pixbuf, gpointer user_data
</USER_FUNCTION>
<USER_FUNCTION>
<NAME>ModuleUpdatedNotifyFunc</NAME>
<RETURNS>void </RETURNS>
GdkPixbuf *pixbuf, gpointer user_data, guint x, guint y, guint width, guint height
</USER_FUNCTION>
<STRUCT>
<NAME>GdkPixbufModule</NAME>
</STRUCT>
@ -37,7 +42,7 @@ struct GdkPixbufModule {
GdkPixbuf *(* load_xpm_data) (const gchar **data);
/* Incremental loading */
gpointer (* begin_load) (ModulePreparedNotifyFunc func, gpointer user_data);
gpointer (* begin_load) (ModulePreparedNotifyFunc prepare_func, ModuleUpdatedNotifyFunc update_func, gpointer user_data);
void (* stop_load) (gpointer context);
gboolean (* load_increment)(gpointer context, const gchar *buf, guint size);
};

1
docs/reference/gdk-pixbuf/gdk-pixbuf-sections.txt
View File

@ -75,6 +75,7 @@ GdkPixbufLoader
<SECTION>
<FILE>gdk-pixbuf-io</FILE>
ModulePreparedNotifyFunc
ModuleUpdatedNotifyFunc
GdkPixbufModule
gdk_pixbuf_get_module
gdk_pixbuf_load_module

40
docs/reference/gdk-pixbuf/tmpl/creating.sgml
View File

@ -1,18 +1,46 @@
<!-- ##### SECTION Title ##### -->
Creating a Pixbuf from Data in Memory
Image Data in Memory
<!-- ##### SECTION Short_Description ##### -->
Creating a pixbuf from image data that is already in memory.
<!-- ##### SECTION Long_Description ##### -->
<para>
The most basic way to create a pixbuf is to wrap an existing
#ArtPixBuf structure with a #GdkPixbuf to add reference counting
capabilities to it. The gdk_pixbuf_new_from_art_pixbuf() performs
this operation.
</para>
<para>
As a convenience, you can use the gdk_pixbuf_new_from_data()
function to wrap an existing data buffer with a #GdkPixbuf. You
need to specify the destroy notification function that will be
called when the data buffer needs to be freed; this will happen
when the pixbuf's reference count drops to zero and thus the
#ArtPixBuf needs to be destroyed. 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>
<!-- ##### SECTION See_Also ##### -->
<para>
</para>
<para>
#ArtPixBuf
</para>
<!-- ##### FUNCTION gdk_pixbuf_new_from_art_pixbuf ##### -->
<para>
@ -58,7 +86,7 @@ Creating a pixbuf from image data that is already in memory.
</para>
@data:
@Returns:
@Returns:
<!--
Local variables:
@ -66,3 +94,5 @@ mode: sgml
sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
End:
-->

4
docs/reference/gdk-pixbuf/tmpl/file-loading.sgml
View File

@ -31,7 +31,7 @@ Loading a pixbuf from a file.
</para>
@filename:
@Returns:
@Returns:
<!--
Local variables:
@ -39,3 +39,5 @@ mode: sgml
sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
End:
-->

13
docs/reference/gdk-pixbuf/tmpl/gdk-pixbuf-io.sgml
View File

@ -23,6 +23,19 @@ gdk-pixbuf-io
@user_data:
<!-- ##### USER_FUNCTION ModuleUpdatedNotifyFunc ##### -->
<para>
</para>
@pixbuf:
@user_data:
@x:
@y:
@width:
@height:
<!-- ##### STRUCT GdkPixbufModule ##### -->
<para>

32
docs/reference/gdk-pixbuf/tmpl/gdk-pixbuf.sgml
View File

@ -34,8 +34,8 @@ the image data.
</para>
@pixbuf:
@Returns:
@pixbuf:
@Returns:
<!-- ##### FUNCTION gdk_pixbuf_get_n_channels ##### -->
@ -43,8 +43,8 @@ the image data.
</para>
@pixbuf:
@Returns:
@pixbuf:
@Returns:
<!-- ##### FUNCTION gdk_pixbuf_get_has_alpha ##### -->
@ -52,8 +52,8 @@ the image data.
</para>
@pixbuf:
@Returns:
@pixbuf:
@Returns:
<!-- ##### FUNCTION gdk_pixbuf_get_bits_per_sample ##### -->
@ -61,8 +61,8 @@ the image data.
</para>
@pixbuf:
@Returns:
@pixbuf:
@Returns:
<!-- ##### FUNCTION gdk_pixbuf_get_pixels ##### -->
@ -70,8 +70,8 @@ the image data.
</para>
@pixbuf:
@Returns:
@pixbuf:
@Returns:
<!-- ##### FUNCTION gdk_pixbuf_get_width ##### -->
@ -79,8 +79,8 @@ the image data.
</para>
@pixbuf:
@Returns:
@pixbuf:
@Returns:
<!-- ##### FUNCTION gdk_pixbuf_get_height ##### -->
@ -88,8 +88,8 @@ the image data.
</para>
@pixbuf:
@Returns:
@pixbuf:
@Returns:
<!-- ##### FUNCTION gdk_pixbuf_get_rowstride ##### -->
@ -97,7 +97,7 @@ the image data.
</para>
@pixbuf:
@pixbuf:
@Returns:
<!--
@ -106,3 +106,5 @@ mode: sgml
sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
End:
-->

95
docs/reference/gdk-pixbuf/tmpl/gnome-canvas-pixbuf.sgml
View File

@ -2,46 +2,62 @@
GnomeCanvasPixbuf
<!-- ##### SECTION Short_Description ##### -->
Canvas item to display #GdkPixbuf images.
<!-- ##### SECTION Long_Description ##### -->
<para>
<para>
This canvas item displays #GdkPixbuf images. It handles full
affine transformations in both GDK and antialiased modes, and also
supports <ulink
url="http://www.w3.org/Graphics/SVG/">SVG</ulink>-like scaling and
translation semantics for absolute pixel values.
</para>
</para>
<para>
#GdkPixbuf structures may be shared among different pixbuf canvas
items; the pixbuf item uses #GdkPixbuf's reference counting
functions for this.
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
</para>
<para>
#GnomeCanvas, #GdkPixbuf
</para>
<!-- ##### MACRO GNOME_CANVAS_PIXBUF ##### -->
<para>
<para>
Casts a #GtkOjbect to a #GnomeCanvasPixbuf.
</para>
</para>
@obj:
@obj: A GTK+ object.
<!-- ##### ARG GnomeCanvasPixbuf:pixbuf ##### -->
<para>
</para>
<!-- ##### ARG GnomeCanvasPixbuf:width ##### -->
<para>
</para>
<para>
Contains a pointer to a #GdkPixbuf structure that will be used by
the pixbuf canvas item as an image source. When a pixbuf is set
its reference count is incremented; if the pixbuf item kept a
pointer to another #GdkPixbuf structure, the reference count of
this structure will be decremented. When a pixbuf is queried, a
reference count will not be added to the return value; you must do
this yourself if you intend to keep the pixbuf structure around.
</para>
<!-- ##### ARG GnomeCanvasPixbuf:width_set ##### -->
<para>
</para>
<para>
Determines whether the
</para>
<!-- ##### ARG GnomeCanvasPixbuf:width_pixels ##### -->
<para>
</para>
<!-- ##### ARG GnomeCanvasPixbuf:width ##### -->
<para>
Contains the width of the image in the pixbuf canvas item.
</para>
<!-- ##### ARG GnomeCanvasPixbuf:height ##### -->
<para>
@ -57,3 +73,40 @@ GnomeCanvasPixbuf
</para>
<!-- ##### ARG GnomeCanvasPixbuf:x ##### -->
<para>
</para>
<!-- ##### ARG GnomeCanvasPixbuf:x_set ##### -->
<para>
</para>
<!-- ##### ARG GnomeCanvasPixbuf:x_pixels ##### -->
<para>
</para>
<!-- ##### ARG GnomeCanvasPixbuf:y ##### -->
<para>
</para>
<!-- ##### ARG GnomeCanvasPixbuf:y_set ##### -->
<para>
</para>
<!-- ##### ARG GnomeCanvasPixbuf:y_pixels ##### -->
<para>
</para>
<!--
Local variables:
mode: sgml
sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
End:
-->

6
docs/reference/gdk-pixbuf/tmpl/refcounting.sgml
View File

@ -17,8 +17,7 @@ Functions to perform reference counting on a #GdkPixbuf.
<!-- ##### SECTION See_Also ##### -->
<para>
#GdkPixbuf
#ArtPixBuf
#GdkPixbuf, #ArtPixBuf
</para>
<!-- ##### FUNCTION gdk_pixbuf_ref ##### -->
@ -36,10 +35,11 @@ Functions to perform reference counting on a #GdkPixbuf.
@pixbuf:
<!--
Local variables:
mode: sgml
sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
End:
-->

55
docs/reference/gdk-pixbuf/tmpl/rendering.sgml
View File

@ -1,26 +1,48 @@
<!-- ##### SECTION Title ##### -->
rendering
Rendering
<!-- ##### SECTION Short_Description ##### -->
Rendering a Pixbuf to a GDK Drawable.
<!-- ##### SECTION Long_Description ##### -->
<para>
<para>
The GdkPixbuf library provides several convenience functions to
render pixbufs to GDK drawables. It uses the GdkRGB to render the
image data.
</para>
</para>
<para>
At this point there is not a standard alpha channel extension for
the X Window System, so it is not possible to use full opacity
information when painting images to arbitrary drawables. The
GdkPixbuf convenience functions will threshold the opacity
information to create a bi-level clipping mask (black and white),
and use that to draw the image onto a drawable.
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
</para>
<para>
GdkRGB
</para>
<!-- ##### ENUM GdkPixbufAlphaMode ##### -->
<para>
<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>
</para>
@GDK_PIXBUF_ALPHA_BILEVEL:
@GDK_PIXBUF_ALPHA_FULL:
@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.
<!-- ##### FUNCTION gdk_pixbuf_render_to_drawable_alpha ##### -->
<para>
@ -74,6 +96,13 @@ rendering
@dest_y:
@width:
@height:
@alpha_threshold:
@alpha_threshold:
<!--
Local variables:
mode: sgml
sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
End:
-->

6
gdk-pixbuf/ChangeLog
View File

@ -1,3 +1,9 @@
1999-11-04 Federico Mena Quintero <federico@redhat.com>
* doc/tmpl/rendering.sgml: Populated.
* doc/Makefile.am: Added the template files.
1999-11-04 Havoc Pennington <hp@pobox.com>
* src/gdk-pixbuf-render.c (gdk_pixbuf_render_to_drawable): In

4
gdk-pixbuf/gdk-pixbuf-data.c
View File

@ -37,9 +37,9 @@
* drops to zero, or NULL if the data should not be freed.
* @dfunc_data: Closure data to pass to the destroy notification function.
*
* Creates a new &GdkPixbuf out of in-memory RGB data.
* Creates a new #GdkPixbuf out of in-memory RGB data.
*
* Return value: A newly-created &GdkPixbuf structure with a reference count of
* Return value: A newly-created #GdkPixbuf structure with a reference count of
* 1.
**/
GdkPixbuf *

4
gdk-pixbuf/gdk-pixbuf-loader.c
View File

@ -89,10 +89,10 @@ gtk_marshal_NONE__INT_INT_INT_INT (GtkObject *object, GtkSignalFunc func, gpoint
* gdk_pixbuf_loader_get_type:
* @void:
*
* Registers the &GdkPixubfLoader class if necessary, and returns the type ID
* Registers the #GdkPixubfLoader class if necessary, and returns the type ID
* associated to it.
*
* Return value: The type ID of the &GdkPixbufLoader class.
* Return value: The type ID of the #GdkPixbufLoader class.
**/
GtkType
gdk_pixbuf_loader_get_type (void)

10
gdk-pixbuf/gdk-pixbuf.c
View File

@ -81,9 +81,9 @@ gdk_pixbuf_unref (GdkPixbuf *pixbuf)
* gdk_pixbuf_new_from_art_pixbuf:
* @art_pixbuf: A libart pixbuf.
*
* Creates a &GdkPixbuf by wrapping a libart pixbuf.
* Creates a #GdkPixbuf by wrapping a libart pixbuf.
*
* Return value: A newly-created &GdkPixbuf structure with a reference count of
* Return value: A newly-created #GdkPixbuf structure with a reference count of
* 1.
**/
GdkPixbuf *
@ -119,12 +119,12 @@ free_buffer (gpointer user_data, gpointer data)
* @width: Width of image in pixels.
* @height: Height of image in pixels.
*
* Creates a new &GdkPixbuf structure and allocates a buffer for it. The buffer
* Creates a new #GdkPixbuf structure and allocates a buffer for it. The buffer
* has an optimal rowstride. Note that the buffer is not cleared; you will have
* to fill it completely.
*
* Return value: A newly-created &GdkPixbuf, or NULL if not enough memory
* could be allocated for the image buffer.
* Return value: A newly-created #GdkPixbuf with a reference count of 1, or NULL
* if not enough memory could be allocated for the image buffer.
**/
GdkPixbuf *
gdk_pixbuf_new (ArtPixFormat format, gboolean has_alpha, int bits_per_sample,

4
gdk-pixbuf/gnome-canvas-pixbuf.c
View File

@ -108,10 +108,10 @@ static GnomeCanvasItemClass *parent_class;
* gnome_canvas_pixbuf_get_type:
* @void:
*
* Registers the &GnomeCanvasPixbuf class if necessary, and returns the type ID
* Registers the #GnomeCanvasPixbuf class if necessary, and returns the type ID
* associated to it.
*
* Return value: The type ID of the &GnomeCanvasPixbuf class.
* Return value: The type ID of the #GnomeCanvasPixbuf class.
**/
GtkType
gnome_canvas_pixbuf_get_type (void)

23
gdk/gdkpixbuf-render.c
View File

@ -176,10 +176,12 @@ remove_alpha (ArtPixBuf *apb, int x, int y, int width, int height, int *rowstrid
* opacity information for images with an alpha channel; the GC must already
* have the clipping mask set if you want transparent regions to show through.
*
* For an explanation of dither offsets, see the GdkRGB documentation. In brief, the
* dither offset is important when scrolling (so you can redraw half an image but keep the
* dithering "lined up" between the part you drew first and the part you drew previously).
* For unscrolled images, the offset can always be 0.
* For an explanation of dither offsets, see the GdkRGB documentation. In
* brief, the dither offset is important when re-rendering partial regions of an
* image to a rendered version of the full image, or for when the offsets to a
* base position change, as in scrolling. The dither matrix has to be shifted
* for consistent visual results. If you do not have any of these cases, the
* dither offsets can be both zero.
**/
void
gdk_pixbuf_render_to_drawable (GdkPixbuf *pixbuf,
@ -254,12 +256,13 @@ gdk_pixbuf_render_to_drawable (GdkPixbuf *pixbuf,
* Renders a rectangular portion of a pixbuf to a drawable. This is done using
* GdkRGB, so the specified drawable must have the GdkRGB visual and colormap.
*
* This function has a performance penalty; it makes two synchronous
* round trips to the X server (creating a bitmask and a GC), and it
* draws the contents of the bitmask. If performance is crucial,
* consider handling alpha yourself and using
* gdk_pixbuf_render_to_drawable(). On the other hand it's more convenient
* than gdk_pixbuf_render_to_drawable() because it handles the alpha channel.
* When used with #GDK_PIXBUF_ALPHA_BILEVEL, this function has to create a bitmap
* out of the thresholded alpha channel of the image and, it has to set this
* bitmap as the clipping mask for the GC used for drawing. This can be a
* significant performance penalty depending on the size and the complexity of
* the alpha channel of the image. If performance is crucial, consider handling
* the alpha channel yourself (possibly by caching it in your application) and
* using gdk_pixbuf_render_to_drawable() or GdkRGB directly instead.
**/
void
gdk_pixbuf_render_to_drawable_alpha (GdkPixbuf *pixbuf, GdkDrawable *drawable,

4
gtk/gdk-pixbuf-loader.c
View File

@ -89,10 +89,10 @@ gtk_marshal_NONE__INT_INT_INT_INT (GtkObject *object, GtkSignalFunc func, gpoint
* gdk_pixbuf_loader_get_type:
* @void:
*
* Registers the &GdkPixubfLoader class if necessary, and returns the type ID
* Registers the #GdkPixubfLoader class if necessary, and returns the type ID
* associated to it.
*
* Return value: The type ID of the &GdkPixbufLoader class.
* Return value: The type ID of the #GdkPixbufLoader class.
**/
GtkType
gdk_pixbuf_loader_get_type (void)