[gtk+] More GDK documentation tweaks
- From: Matthias Clasen <matthiasc src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [gtk+] More GDK documentation tweaks
- Date: Wed, 9 Feb 2011 07:44:25 +0000 (UTC)
commit 8291530abfc3f74b105d377beb2afc4687c7ffd1
Author: Matthias Clasen <mclasen redhat com>
Date: Wed Feb 9 02:43:07 2011 -0500
More GDK documentation tweaks
gdk/gdkcairo.c | 226 +++++++++++++++++++++++-----------------------
gdk/gdkcairo.h | 46 +++++-----
gdk/gdkcolor.c | 100 +++++++++++---------
gdk/gdkcolor.h | 32 ++++---
gdk/gdkpixbuf-drawable.c | 94 ++++++++++---------
gdk/gdkpixbuf.h | 23 +++---
gdk/gdkrgba.c | 89 ++++++++++--------
gdk/gdkrgba.h | 17 ++--
gdk/gdkwindow.c | 12 ++--
9 files changed, 333 insertions(+), 306 deletions(-)
---
diff --git a/gdk/gdkcairo.c b/gdk/gdkcairo.c
index 0d4b8bd..2ae8b09 100644
--- a/gdk/gdkcairo.c
+++ b/gdk/gdkcairo.c
@@ -8,7 +8,7 @@
*
* This library 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
+ * 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
@@ -27,17 +27,18 @@
/**
* SECTION:cairo_interaction
- * @Short_description: Functions to support using Cairo
+ * @Short_description: Functions to support using cairo
* @Title: Cairo Interaction
*
* <link href="http://cairographics.org";>Cairo</link> is a graphics
* library that supports vector graphics and image compositing that
- * can be used with GDK. GTK+ does all of its drawing using Cairo.
+ * can be used with GDK. GTK+ does all of its drawing using cairo.
*
- * GDK does not wrap the Cairo API, instead it allows to create Cairo
+ * GDK does not wrap the cairo API, instead it allows to create cairo
* contexts which can be used to draw on #GdkWindows. Additional
* functions allow use #GdkRectangles with cairo and to use #GdkColors,
- * #GdkPixbufs and #GdkWindows as sources for drawing operations.
+ * #GdkRGBAs, #GdkPixbufs and #GdkWindows as sources for drawing
+ * operations.
*/
@@ -46,13 +47,13 @@
* @cr: a cairo context
* @rect: (out) (allow-none): return location for the clip, or %NULL
*
- * This is a convenience function around cairo_clip_extents(). It rounds
- * the clip extents to integer coordinates and returns a boolean
- * indicating if a clip area exists.
+ * This is a convenience function around cairo_clip_extents().
+ * It rounds the clip extents to integer coordinates and returns
+ * a boolean indicating if a clip area exists.
*
* Returns: %TRUE if a clip rectangle exists, %FALSE if all of @cr is
- * clipped and all drawing can be skipped.
- **/
+ * clipped and all drawing can be skipped
+ */
gboolean
gdk_cairo_get_clip_rectangle (cairo_t *cr,
GdkRectangle *rect)
@@ -82,35 +83,35 @@ gdk_cairo_get_clip_rectangle (cairo_t *cr,
/**
* gdk_cairo_set_source_color:
- * @cr: a #cairo_t
+ * @cr: a cairo context
* @color: a #GdkColor
*
* Sets the specified #GdkColor as the source color of @cr.
*
* Since: 2.8
- **/
+ */
void
gdk_cairo_set_source_color (cairo_t *cr,
- const GdkColor *color)
+ const GdkColor *color)
{
g_return_if_fail (cr != NULL);
g_return_if_fail (color != NULL);
cairo_set_source_rgb (cr,
- color->red / 65535.,
- color->green / 65535.,
- color->blue / 65535.);
+ color->red / 65535.,
+ color->green / 65535.,
+ color->blue / 65535.);
}
/**
* gdk_cairo_set_source_rgba:
- * @cr: a #cairo_t
+ * @cr: a cairo context
* @rgba: a #GdkRGBA
*
* Sets the specified #GdkRGBA as the source color of @cr.
*
* Since: 3.0
- **/
+ */
void
gdk_cairo_set_source_rgba (cairo_t *cr,
const GdkRGBA *rgba)
@@ -127,37 +128,37 @@ gdk_cairo_set_source_rgba (cairo_t *cr,
/**
* gdk_cairo_rectangle:
- * @cr: a #cairo_t
+ * @cr: a cairo context
* @rectangle: a #GdkRectangle
- *
+ *
* Adds the given rectangle to the current path of @cr.
*
* Since: 2.8
- **/
+ */
void
gdk_cairo_rectangle (cairo_t *cr,
- const GdkRectangle *rectangle)
+ const GdkRectangle *rectangle)
{
g_return_if_fail (cr != NULL);
g_return_if_fail (rectangle != NULL);
cairo_rectangle (cr,
- rectangle->x, rectangle->y,
- rectangle->width, rectangle->height);
+ rectangle->x, rectangle->y,
+ rectangle->width, rectangle->height);
}
/**
* gdk_cairo_region:
- * @cr: a #cairo_t
+ * @cr: a cairo context
* @region: a #cairo_region_t
- *
+ *
* Adds the given region to the current path of @cr.
*
* Since: 2.8
- **/
+ */
void
gdk_cairo_region (cairo_t *cr,
- const cairo_region_t *region)
+ const cairo_region_t *region)
{
cairo_rectangle_int_t box;
gint n_boxes, i;
@@ -176,22 +177,23 @@ gdk_cairo_region (cairo_t *cr,
/**
* gdk_cairo_set_source_pixbuf:
- * @cr: a #Cairo context
+ * @cr: a cairo context
* @pixbuf: a #GdkPixbuf
* @pixbuf_x: X coordinate of location to place upper left corner of @pixbuf
* @pixbuf_y: Y coordinate of location to place upper left corner of @pixbuf
- *
- * Sets the given pixbuf as the source pattern for the Cairo context.
+ *
+ * Sets the given pixbuf as the source pattern for @cr.
+ *
* The pattern has an extend mode of %CAIRO_EXTEND_NONE and is aligned
- * so that the origin of @pixbuf is @pixbuf_x, @pixbuf_y
+ * so that the origin of @pixbuf is @pixbuf_x, @pixbuf_y.
*
* Since: 2.8
- **/
+ */
void
gdk_cairo_set_source_pixbuf (cairo_t *cr,
- const GdkPixbuf *pixbuf,
- double pixbuf_x,
- double pixbuf_y)
+ const GdkPixbuf *pixbuf,
+ gdouble pixbuf_x,
+ gdouble pixbuf_y)
{
gint width = gdk_pixbuf_get_width (pixbuf);
gint height = gdk_pixbuf_get_height (pixbuf);
@@ -217,7 +219,7 @@ gdk_cairo_set_source_pixbuf (cairo_t *cr,
width, height, cairo_stride);
cairo_surface_set_user_data (surface, &key,
- cairo_pixels, (cairo_destroy_func_t)g_free);
+ cairo_pixels, (cairo_destroy_func_t)g_free);
for (j = height; j; j--)
{
@@ -225,51 +227,51 @@ gdk_cairo_set_source_pixbuf (cairo_t *cr,
guchar *q = cairo_pixels;
if (n_channels == 3)
- {
- guchar *end = p + 3 * width;
-
- while (p < end)
- {
+ {
+ guchar *end = p + 3 * width;
+
+ while (p < end)
+ {
#if G_BYTE_ORDER == G_LITTLE_ENDIAN
- q[0] = p[2];
- q[1] = p[1];
- q[2] = p[0];
-#else
- q[1] = p[0];
- q[2] = p[1];
- q[3] = p[2];
+ q[0] = p[2];
+ q[1] = p[1];
+ q[2] = p[0];
+#else
+ q[1] = p[0];
+ q[2] = p[1];
+ q[3] = p[2];
#endif
- p += 3;
- q += 4;
- }
- }
+ p += 3;
+ q += 4;
+ }
+ }
else
- {
- guchar *end = p + 4 * width;
- guint t1,t2,t3;
-
+ {
+ guchar *end = p + 4 * width;
+ guint t1,t2,t3;
+
#define MULT(d,c,a,t) G_STMT_START { t = c * a + 0x7f; d = ((t >> 8) + t) >> 8; } G_STMT_END
- while (p < end)
- {
+ while (p < end)
+ {
#if G_BYTE_ORDER == G_LITTLE_ENDIAN
- MULT(q[0], p[2], p[3], t1);
- MULT(q[1], p[1], p[3], t2);
- MULT(q[2], p[0], p[3], t3);
- q[3] = p[3];
-#else
- q[0] = p[3];
- MULT(q[1], p[0], p[3], t1);
- MULT(q[2], p[1], p[3], t2);
- MULT(q[3], p[2], p[3], t3);
+ MULT(q[0], p[2], p[3], t1);
+ MULT(q[1], p[1], p[3], t2);
+ MULT(q[2], p[0], p[3], t3);
+ q[3] = p[3];
+#else
+ q[0] = p[3];
+ MULT(q[1], p[0], p[3], t1);
+ MULT(q[2], p[1], p[3], t2);
+ MULT(q[3], p[2], p[3], t3);
#endif
-
- p += 4;
- q += 4;
- }
-
+
+ p += 4;
+ q += 4;
+ }
+
#undef MULT
- }
+ }
gdk_pixels += gdk_rowstride;
cairo_pixels += cairo_stride;
@@ -281,12 +283,13 @@ gdk_cairo_set_source_pixbuf (cairo_t *cr,
/**
* gdk_cairo_set_source_window:
- * @cr: a #Cairo context
+ * @cr: a cairo context
* @window: a #GdkWindow
* @x: X coordinate of location to place upper left corner of @window
* @y: Y coordinate of location to place upper left corner of @window
*
- * Sets the given window as the source pattern for the Cairo context.
+ * Sets the given window as the source pattern for @cr.
+ *
* The pattern has an extend mode of %CAIRO_EXTEND_NONE and is aligned
* so that the origin of @window is @x, @y. The window contains all its
* subwindows when rendering.
@@ -299,11 +302,11 @@ gdk_cairo_set_source_pixbuf (cairo_t *cr,
void
gdk_cairo_set_source_window (cairo_t *cr,
GdkWindow *window,
- double x,
- double y)
+ gdouble x,
+ gdouble y)
{
cairo_surface_t *surface;
-
+
g_return_if_fail (cr != NULL);
g_return_if_fail (GDK_IS_WINDOW (window));
@@ -312,23 +315,24 @@ gdk_cairo_set_source_window (cairo_t *cr,
cairo_surface_destroy (surface);
}
-/**
+/*
* _gdk_cairo_surface_extents:
* @surface: surface to measure
* @extents: (out): rectangle to put the extents
*
* Measures the area covered by @surface and puts it into @extents.
+ *
* Note that this function respects device offsets set on @surface.
- * if @surface is unbounded, the resulting extents will be empty and
+ * If @surface is unbounded, the resulting extents will be empty and
* not be a maximal sized rectangle. This is to avoid careless coding.
* You must explicitly check the return value of you want to handle
* that case.
*
- * Returns: %TRUE if the extents fit in a #GdkRectangle, %FALSE if not.
- **/
+ * Returns: %TRUE if the extents fit in a #GdkRectangle, %FALSE if not
+ */
gboolean
_gdk_cairo_surface_extents (cairo_surface_t *surface,
- GdkRectangle *extents)
+ GdkRectangle *extents)
{
double x1, x2, y1, y2;
cairo_t *cr;
@@ -346,7 +350,7 @@ _gdk_cairo_surface_extents (cairo_surface_t *surface,
y2 = ceil (y2);
x2 -= x1;
y2 -= y1;
-
+
if (x1 < G_MININT || x1 > G_MAXINT ||
y1 < G_MININT || y1 > G_MAXINT ||
x2 > G_MAXINT || y2 > G_MAXINT)
@@ -371,14 +375,15 @@ _gdk_cairo_surface_extents (cairo_surface_t *surface,
*/
/**
* gdk_cairo_region_create_from_surface:
- * @surface: A surface
+ * @surface: a cairo surface
*
- * Creates region that describes covers the area where the given @surface
- * is more than 50% opaque. This function takes into account device
- * offsets that might be set with cairo_surface_set_device_offset().
+ * Creates region that describes covers the area where the given
+ * @surface is more than 50% opaque.
*
- * Returns: A #cairo_region_t. This must be freed with cairo_region_destroy()
- * when you are done.
+ * This function takes into account device offsets that might be
+ * set with cairo_surface_set_device_offset().
+ *
+ * Returns: A #cairo_region_t; must be freed with cairo_region_destroy()
*/
cairo_region_t *
gdk_cairo_region_create_from_surface (cairo_surface_t *surface)
@@ -417,37 +422,36 @@ gdk_cairo_region_create_from_surface (cairo_surface_t *surface)
for (y = 0; y < extents.height; y++)
{
for (x = 0; x < extents.width; x++)
- {
- /* Search for a continuous range of "non transparent pixels"*/
- gint x0 = x;
- while (x < extents.width)
- {
- if (((data[x / 8] >> (x%8)) & 1) == 0)
- /* This pixel is "transparent"*/
- break;
- x++;
- }
-
- if (x > x0)
- {
- /* Add the pixels (x0, y) to (x, y+1) as a new rectangle
- * in the region
- */
+ {
+ /* Search for a continuous range of "non transparent pixels"*/
+ gint x0 = x;
+ while (x < extents.width)
+ {
+ if (((data[x / 8] >> (x%8)) & 1) == 0)
+ /* This pixel is "transparent"*/
+ break;
+ x++;
+ }
+
+ if (x > x0)
+ {
+ /* Add the pixels (x0, y) to (x, y+1) as a new rectangle
+ * in the region
+ */
rect.x = x0;
rect.width = x - x0;
rect.y = y;
rect.height = 1;
cairo_region_union_rectangle (region, &rect);
- }
- }
+ }
+ }
data += stride;
}
cairo_surface_destroy (image);
-
+
cairo_region_translate (region, extents.x, extents.y);
return region;
}
-
diff --git a/gdk/gdkcairo.h b/gdk/gdkcairo.h
index 67e08aa..f2cf7bd 100644
--- a/gdk/gdkcairo.h
+++ b/gdk/gdkcairo.h
@@ -31,31 +31,31 @@
G_BEGIN_DECLS
-cairo_t *gdk_cairo_create (GdkWindow *window);
-gboolean gdk_cairo_get_clip_rectangle(cairo_t *cr,
- GdkRectangle *rect);
-
-void gdk_cairo_set_source_color (cairo_t *cr,
- const GdkColor *color);
-void gdk_cairo_set_source_rgba (cairo_t *cr,
- const GdkRGBA *rgba);
-void gdk_cairo_set_source_pixbuf (cairo_t *cr,
- const GdkPixbuf *pixbuf,
- double pixbuf_x,
- double pixbuf_y);
-void gdk_cairo_set_source_window (cairo_t *cr,
- GdkWindow *window,
- double x,
- double y);
-
-void gdk_cairo_rectangle (cairo_t *cr,
- const GdkRectangle *rectangle);
-void gdk_cairo_region (cairo_t *cr,
- const cairo_region_t *region);
+cairo_t * gdk_cairo_create (GdkWindow *window);
+gboolean gdk_cairo_get_clip_rectangle (cairo_t *cr,
+ GdkRectangle *rect);
+
+void gdk_cairo_set_source_color (cairo_t *cr,
+ const GdkColor *color);
+void gdk_cairo_set_source_rgba (cairo_t *cr,
+ const GdkRGBA *rgba);
+void gdk_cairo_set_source_pixbuf (cairo_t *cr,
+ const GdkPixbuf *pixbuf,
+ gdouble pixbuf_x,
+ gdouble pixbuf_y);
+void gdk_cairo_set_source_window (cairo_t *cr,
+ GdkWindow *window,
+ gdouble x,
+ gdouble y);
+
+void gdk_cairo_rectangle (cairo_t *cr,
+ const GdkRectangle *rectangle);
+void gdk_cairo_region (cairo_t *cr,
+ const cairo_region_t *region);
cairo_region_t *
- gdk_cairo_region_create_from_surface
- (cairo_surface_t *surface);
+ gdk_cairo_region_create_from_surface
+ (cairo_surface_t *surface);
G_END_DECLS
diff --git a/gdk/gdkcolor.c b/gdk/gdkcolor.c
index d4ab63c..ace9101 100644
--- a/gdk/gdkcolor.c
+++ b/gdk/gdkcolor.c
@@ -37,23 +37,29 @@
* SECTION:colors
* @Short_description: Manipulation of colors
* @Title: Colors
+ *
+ * A #GdkColor represents a color.
+ *
+ * When working with cairo, it is often more convenient
+ * to use a #GdkRGBA instead.
*/
/**
* gdk_color_copy:
- * @color: a #GdkColor.
- *
- * Makes a copy of a color structure. The result
- * must be freed using gdk_color_free().
- *
- * Return value: a copy of @color.
- **/
+ * @color: a #GdkColor
+ *
+ * Makes a copy of a color structure.
+ *
+ * The result must be freed using gdk_color_free().
+ *
+ * Return value: a copy of @color
+ */
GdkColor*
gdk_color_copy (const GdkColor *color)
{
GdkColor *new_color;
-
+
g_return_val_if_fail (color != NULL, NULL);
new_color = g_slice_new (GdkColor);
@@ -63,11 +69,10 @@ gdk_color_copy (const GdkColor *color)
/**
* gdk_color_free:
- * @color: a #GdkColor.
- *
- * Frees a color structure created with
- * gdk_color_copy().
- **/
+ * @color: a #GdkColor
+ *
+ * Frees a color structure created with gdk_color_copy().
+ */
void
gdk_color_free (GdkColor *color)
{
@@ -78,41 +83,41 @@ gdk_color_free (GdkColor *color)
/**
* gdk_color_hash:
- * @colora: a #GdkColor.
- *
+ * @color: a #GdkColor
+ *
* A hash function suitable for using for a hash
- * table that stores #GdkColor's.
- *
- * Return value: The hash function applied to @colora
- **/
+ * table that stores #GdkColors.
+ *
+ * Return value: The hash function applied to @color
+ */
guint
-gdk_color_hash (const GdkColor *colora)
+gdk_color_hash (const GdkColor *color)
{
- return ((colora->red) +
- (colora->green << 11) +
- (colora->blue << 22) +
- (colora->blue >> 6));
+ return ((color->red) +
+ (color->green << 11) +
+ (color->blue << 22) +
+ (color->blue >> 6));
}
/**
* gdk_color_equal:
- * @colora: a #GdkColor.
- * @colorb: another #GdkColor.
- *
- * Compares two colors.
- *
+ * @colora: a #GdkColor
+ * @colorb: another #GdkColor
+ *
+ * Compares two colors.
+ *
* Return value: %TRUE if the two colors compare equal
- **/
+ */
gboolean
gdk_color_equal (const GdkColor *colora,
- const GdkColor *colorb)
+ const GdkColor *colorb)
{
g_return_val_if_fail (colora != NULL, FALSE);
g_return_val_if_fail (colorb != NULL, FALSE);
return ((colora->red == colorb->red) &&
- (colora->green == colorb->green) &&
- (colora->blue == colorb->blue));
+ (colora->green == colorb->green) &&
+ (colora->blue == colorb->blue));
}
G_DEFINE_BOXED_TYPE (GdkColor, gdk_color,
@@ -121,25 +126,28 @@ G_DEFINE_BOXED_TYPE (GdkColor, gdk_color,
/**
* gdk_color_parse:
- * @spec: the string specifying the color.
+ * @spec: the string specifying the color
* @color: (out): the #GdkColor to fill in
*
* Parses a textual specification of a color and fill in the
* <structfield>red</structfield>, <structfield>green</structfield>,
* and <structfield>blue</structfield> fields of a #GdkColor
- * structure. The string can either one of a large set of standard
- * names. (Taken from the X11 <filename>rgb.txt</filename> file), or
+ * structure.
+ *
+ * The string can either one of a large set of standard names
+ * (taken from the X11 <filename>rgb.txt</filename> file), or
* it can be a hex value in the form '#rgb' '#rrggbb'
- * '#rrrgggbbb' or '#rrrrggggbbbb' where 'r', 'g' and 'b' are
- * hex digits of the red, green, and blue components of the color,
- * respectively. (White in the four forms is '#fff' '#ffffff'
- * '#fffffffff' and '#ffffffffffff')
- *
- * Return value: %TRUE if the parsing succeeded.
- **/
+ * '#rrrgggbbb' or '#rrrrggggbbbb' where 'r', 'g' and
+ * 'b' are hex digits of the red, green, and blue components
+ * of the color, respectively. (White in the four forms is
+ * '#fff', '#ffffff', '#fffffffff' and
+ * '#ffffffffffff').
+ *
+ * Return value: %TRUE if the parsing succeeded
+ */
gboolean
gdk_color_parse (const gchar *spec,
- GdkColor *color)
+ GdkColor *color)
{
PangoColor pango_color;
@@ -164,10 +172,12 @@ gdk_color_parse (const gchar *spec,
* <literal>g</literal> and <literal>b</literal> are hex digits
* representing the red, green and blue components respectively.
*
+ * The returned string can be parsed by gdk_color_parse().
+ *
* Return value: a newly-allocated text string
*
* Since: 2.12
- **/
+ */
gchar *
gdk_color_to_string (const GdkColor *color)
{
diff --git a/gdk/gdkcolor.h b/gdk/gdkcolor.h
index 4f9ee2a..cab28a6 100644
--- a/gdk/gdkcolor.h
+++ b/gdk/gdkcolor.h
@@ -39,16 +39,16 @@ G_BEGIN_DECLS
/**
* GdkColor:
- * @pixel: For allocated colors, the value used to
- * draw this color on the screen.
+ * @pixel: For allocated colors, the pixel value used to
+ * draw this color on the screen. Not used anymore.
* @red: The red component of the color. This is
- * a value between 0 and 65535, with 65535 indicating
- * full intensitiy.
- * @green: The green component of the color.
- * @blue: The blue component of the color.
+ * a value between 0 and 65535, with 65535 indicating
+ * full intensitiy
+ * @green: The green component of the color
+ * @blue: The blue component of the color
*
- * The #GdkColor structure is used to describe an
- * allocated or unallocated color.
+ * The #GdkColor structure is used to describe a color,
+ * similar to the XColor struct used in the X11 drawing API.
*/
struct _GdkColor
{
@@ -58,18 +58,20 @@ struct _GdkColor
guint16 blue;
};
-#define GDK_TYPE_COLOR (gdk_color_get_type ())
+#define GDK_TYPE_COLOR (gdk_color_get_type ())
+
+GType gdk_color_get_type (void) G_GNUC_CONST;
GdkColor *gdk_color_copy (const GdkColor *color);
void gdk_color_free (GdkColor *color);
-gboolean gdk_color_parse (const gchar *spec,
- GdkColor *color);
-guint gdk_color_hash (const GdkColor *colora);
+
+guint gdk_color_hash (const GdkColor *color);
gboolean gdk_color_equal (const GdkColor *colora,
- const GdkColor *colorb);
-gchar * gdk_color_to_string (const GdkColor *color);
+ const GdkColor *colorb);
-GType gdk_color_get_type (void) G_GNUC_CONST;
+gboolean gdk_color_parse (const gchar *spec,
+ GdkColor *color);
+gchar * gdk_color_to_string (const GdkColor *color);
G_END_DECLS
diff --git a/gdk/gdkpixbuf-drawable.c b/gdk/gdkpixbuf-drawable.c
index fd14b9e..67d890c 100644
--- a/gdk/gdkpixbuf-drawable.c
+++ b/gdk/gdkpixbuf-drawable.c
@@ -34,12 +34,14 @@
/**
* SECTION:pixbufs
- * @Short_description: Functions for rendering pixbufs on drawables
+ * @Short_description: Functions for obtaining pixbufs
* @Title: Pixbufs
*
- * These functions allow to render pixbufs on drawables. Pixbufs are
- * client-side images. For details on how to create and manipulate
- * pixbufs, see the #GdkPixbuf API documentation.
+ * Pixbufs are client-side images. For details on how to create
+ * and manipulate pixbufs, see the #GdkPixbuf API documentation.
+ *
+ * The functions described here allow to obtain pixbufs from
+ * #GdkWindows and cairo surfaces.
*/
@@ -55,7 +57,7 @@
* representation inside a #GdkPixbuf. In other words, copies
* image data from a server-side drawable to a client-side RGB(A) buffer.
* This allows you to efficiently read individual pixels on the client side.
- *
+ *
* This function will create an RGB pixbuf with 8 bits per channel with
* the same size specified by the @width and @height arguments. The pixbuf
* will contain an alpha channel if the @window contains one.
@@ -78,16 +80,18 @@
* it returns %NULL; so check the return value.)
*
* Return value: (transfer full): A newly-created pixbuf with a reference
- * count of 1, or %NULL on error
- **/
+ * count of 1, or %NULL on error
+ */
GdkPixbuf *
-gdk_pixbuf_get_from_window (GdkWindow *src,
- int src_x, int src_y,
- int width, int height)
+gdk_pixbuf_get_from_window (GdkWindow *src,
+ gint src_x,
+ gint src_y,
+ gint width,
+ gint height)
{
cairo_surface_t *surface;
GdkPixbuf *dest;
-
+
g_return_val_if_fail (GDK_IS_WINDOW (src), NULL);
g_return_val_if_fail (gdk_window_is_viewable (src), NULL);
@@ -99,7 +103,7 @@ gdk_pixbuf_get_from_window (GdkWindow *src,
return dest;
}
-
+
static cairo_format_t
gdk_cairo_format_for_content (cairo_content_t content)
{
@@ -117,11 +121,11 @@ gdk_cairo_format_for_content (cairo_content_t content)
static cairo_surface_t *
gdk_cairo_surface_coerce_to_image (cairo_surface_t *surface,
- cairo_content_t content,
- int src_x,
- int src_y,
- int width,
- int height)
+ cairo_content_t content,
+ int src_x,
+ int src_y,
+ int width,
+ int height)
{
cairo_surface_t *copy;
cairo_t *cr;
@@ -140,14 +144,14 @@ gdk_cairo_surface_coerce_to_image (cairo_surface_t *surface,
}
static void
-convert_alpha (guchar *dest_data,
- int dest_stride,
- guchar *src_data,
- int src_stride,
- int src_x,
- int src_y,
- int width,
- int height)
+convert_alpha (guchar *dest_data,
+ int dest_stride,
+ guchar *src_data,
+ int src_stride,
+ int src_x,
+ int src_y,
+ int width,
+ int height)
{
int x, y;
@@ -180,14 +184,14 @@ convert_alpha (guchar *dest_data,
}
static void
-convert_no_alpha (guchar *dest_data,
- int dest_stride,
- guchar *src_data,
- int src_stride,
- int src_x,
- int src_y,
- int width,
- int height)
+convert_no_alpha (guchar *dest_data,
+ int dest_stride,
+ guchar *src_data,
+ int src_stride,
+ int src_x,
+ int src_y,
+ int width,
+ int height)
{
int x, y;
@@ -220,22 +224,22 @@ convert_no_alpha (guchar *dest_data,
* individual pixels from cairo surfaces. For #GdkWindows, use
* gdk_pixbuf_get_from_window() instead.
*
- * This function will create an RGB pixbuf with 8 bits per channel. The pixbuf
- * will contain an alpha channel if the @surface contains one.
+ * This function will create an RGB pixbuf with 8 bits per channel.
+ * The pixbuf will contain an alpha channel if the @surface contains one.
*
- * Return value: (transfer full): A newly-created pixbuf with a reference count
- * of 1, or %NULL on error
- **/
+ * Return value: (transfer full): A newly-created pixbuf with a reference
+ * count of 1, or %NULL on error
+ */
GdkPixbuf *
gdk_pixbuf_get_from_surface (cairo_surface_t *surface,
- int src_x,
- int src_y,
- int width,
- int height)
+ gint src_x,
+ gint src_y,
+ gint width,
+ gint height)
{
cairo_content_t content;
GdkPixbuf *dest;
-
+
/* General sanity checks */
g_return_val_if_fail (surface != NULL, NULL);
g_return_val_if_fail (width > 0 && height > 0, NULL);
@@ -246,7 +250,8 @@ gdk_pixbuf_get_from_surface (cairo_surface_t *surface,
8,
width, height);
- surface = gdk_cairo_surface_coerce_to_image (surface, content, src_x, src_y,
+ surface = gdk_cairo_surface_coerce_to_image (surface, content,
+ src_x, src_y,
width, height);
cairo_surface_flush (surface);
if (cairo_surface_status (surface) || dest == NULL)
@@ -273,4 +278,3 @@ gdk_pixbuf_get_from_surface (cairo_surface_t *surface,
cairo_surface_destroy (surface);
return dest;
}
-
diff --git a/gdk/gdkpixbuf.h b/gdk/gdkpixbuf.h
index 61a1392..b7b09d2 100644
--- a/gdk/gdkpixbuf.h
+++ b/gdk/gdkpixbuf.h
@@ -37,18 +37,17 @@
G_BEGIN_DECLS
-/* Fetching a region from a drawable */
-GdkPixbuf *gdk_pixbuf_get_from_window (GdkWindow *window,
- int src_x,
- int src_y,
- int width,
- int height);
-
-GdkPixbuf *gdk_pixbuf_get_from_surface (cairo_surface_t *surface,
- int src_x,
- int src_y,
- int width,
- int height);
+GdkPixbuf *gdk_pixbuf_get_from_window (GdkWindow *window,
+ gint src_x,
+ gint src_y,
+ gint width,
+ gint height);
+
+GdkPixbuf *gdk_pixbuf_get_from_surface (cairo_surface_t *surface,
+ gint src_x,
+ gint src_y,
+ gint width,
+ gint height);
G_END_DECLS
diff --git a/gdk/gdkrgba.c b/gdk/gdkrgba.c
index de06cb2..f5e20c5 100644
--- a/gdk/gdkrgba.c
+++ b/gdk/gdkrgba.c
@@ -34,7 +34,7 @@
* @Title: RGBA Colors
*
* The #GdkRGBA struct is a convenient way to pass rgba colors around.
- * It's based on cairo's way to deal with colors and mirros its behavior.
+ * It's based on cairo's way to deal with colors and mirrors its behavior.
* All values are in the range from 0.0 to 1.0 inclusive. So the color
* (0.0, 0.0, 0.0, 0.0) represents transparent black and
* (1.0, 1.0, 1.0, 1.0) is opaque white. Other values will be clamped
@@ -46,28 +46,28 @@ G_DEFINE_BOXED_TYPE (GdkRGBA, gdk_rgba,
/**
* GdkRGBA:
- * @red: The intensity of the red channel from 0.0 to 1.0 inclusive.
- * @green: The intensity of the green channel from 0.0 to 1.0 inclusive.
- * @blue: The intensity of the blue channel from 0.0 to 1.0 inclusive.
+ * @red: The intensity of the red channel from 0.0 to 1.0 inclusive
+ * @green: The intensity of the green channel from 0.0 to 1.0 inclusive
+ * @blue: The intensity of the blue channel from 0.0 to 1.0 inclusive
* @alpha: The opacity of the color from 0.0 for completely translucent to
- * 1.0 for opaque.
+ * 1.0 for opaque
*
- * The GdkRGBA structure is used to pass around color data. When using it
- * as struct members or on the stack, you want to use the struct directly
- * and not allocate it.
+ * The GdkRGBA structure is used to represent a (possibly translucent)
+ * color, in a way that is compatible with cairos notion of color.
*/
/**
* gdk_rgba_copy:
* @rgba: a #GdkRGBA
*
- * Makes a copy of a #GdkRGBA structure, the result must be freed
- * through gdk_rgba_free().
+ * Makes a copy of a #GdkRGBA structure.
*
- * Returns: A newly allocated #GdkRGBA
+ * The result must be freed through gdk_rgba_free().
+ *
+ * Returns: A newly allocated #GdkRGBA, with the same contents as @rgba
*
* Since: 3.0
- **/
+ */
GdkRGBA *
gdk_rgba_copy (const GdkRGBA *rgba)
{
@@ -89,7 +89,7 @@ gdk_rgba_copy (const GdkRGBA *rgba)
* Frees a #GdkRGBA struct created with gdk_rgba_copy()
*
* Since: 3.0
- **/
+ */
void
gdk_rgba_free (GdkRGBA *rgba)
{
@@ -111,7 +111,7 @@ gdk_rgba_free (GdkRGBA *rgba)
*/
static double
parse_rgb_value (const char *str,
- char **endp)
+ char **endp)
{
double number;
const char *p;
@@ -168,7 +168,7 @@ parse_rgb_value (const char *str,
* Returns: %TRUE if the parsing succeeded
*
* Since: 3.0
- **/
+ */
gboolean
gdk_rgba_parse (GdkRGBA *rgba,
const gchar *spec)
@@ -193,7 +193,8 @@ gdk_rgba_parse (GdkRGBA *rgba,
PangoColor pango_color;
/* Resort on PangoColor for rgb.txt color
- * map and '#' prefixed colors */
+ * map and '#' prefixed colors
+ */
if (pango_color_parse (&pango_color, str))
{
if (rgba)
@@ -272,37 +273,37 @@ gdk_rgba_parse (GdkRGBA *rgba,
/**
* gdk_rgba_hash:
- * @p: (type GdkRGBA): a #GdkRGBA pointer.
+ * @p: (type GdkRGBA): a #GdkRGBA pointer
*
* A hash function suitable for using for a hash
- * table that stores #GdkRGBA<!-- -->s.
+ * table that stores #GdkRGBAs.
*
- * Return value: The hash function applied to @p
+ * Return value: The hash value for @p
*
* Since: 3.0
- **/
+ */
guint
gdk_rgba_hash (gconstpointer p)
{
const GdkRGBA *rgba = p;
return ((guint) (rgba->red * 65535) +
- ((guint) (rgba->green * 65535) << 11) +
- ((guint) (rgba->blue * 65535) << 22) +
- ((guint) (rgba->alpha * 65535) >> 6));
+ ((guint) (rgba->green * 65535) << 11) +
+ ((guint) (rgba->blue * 65535) << 22) +
+ ((guint) (rgba->alpha * 65535) >> 6));
}
/**
* gdk_rgba_equal:
- * @p1: (type GdkRGBA): a #GdkRGBA pointer.
- * @p2: (type GdkRGBA): another #GdkRGBA pointer.
+ * @p1: (type GdkRGBA): a #GdkRGBA pointer
+ * @p2: (type GdkRGBA): another #GdkRGBA pointer
*
* Compares two RGBA colors.
*
* Return value: %TRUE if the two colors compare equal
*
* Since: 3.0
- **/
+ */
gboolean
gdk_rgba_equal (gconstpointer p1,
gconstpointer p2)
@@ -325,27 +326,35 @@ gdk_rgba_equal (gconstpointer p1,
* gdk_rgba_to_string:
* @rgba: a #GdkRGBA
*
- * Returns a textual specification of @rgba in the form <literal>rgb
- * (r, g, b)</literal> or <literal>rgba (r, g, b, a)</literal>,
- * where 'r', 'g', 'b' and 'a' represent the red, green, blue and alpha values
- * respectively. r, g, and b are integers in the range 0 to 255, and a
- * is a floating point value in the range 0 to 1.
+ * Returns a textual specification of @rgba in the form
+ * <literal>rgb (r, g, b)</literal> or
+ * <literal>rgba (r, g, b, a)</literal>,
+ * where 'r', 'g', 'b' and 'a' represent the red, green,
+ * blue and alpha values respectively. r, g, and b are
+ * represented as integers in the range 0 to 255, and a
+ * is represented as floating point value in the range 0 to 1.
*
- * (These string forms are string forms those supported by the CSS3 colors module)
+ * These string forms are string forms those supported by
+ * the CSS3 colors module, and can be parsed by gdk_rgba_parse().
+ *
+ * Note that this string representation may loose some
+ * precision, since r, g and b are represented as 8-bit
+ * integers. If this is a concern, you should use a
+ * different representation.
*
* Returns: A newly allocated text string
*
* Since: 3.0
- **/
+ */
gchar *
gdk_rgba_to_string (const GdkRGBA *rgba)
{
if (rgba->alpha > 0.999)
{
return g_strdup_printf ("rgb(%d,%d,%d)",
- (int)(0.5 + CLAMP (rgba->red, 0., 1.) * 255.),
- (int)(0.5 + CLAMP (rgba->green, 0., 1.) * 255.),
- (int)(0.5 + CLAMP (rgba->blue, 0., 1.) * 255.));
+ (int)(0.5 + CLAMP (rgba->red, 0., 1.) * 255.),
+ (int)(0.5 + CLAMP (rgba->green, 0., 1.) * 255.),
+ (int)(0.5 + CLAMP (rgba->blue, 0., 1.) * 255.));
}
else
{
@@ -354,9 +363,9 @@ gdk_rgba_to_string (const GdkRGBA *rgba)
g_ascii_dtostr (alpha, G_ASCII_DTOSTR_BUF_SIZE, CLAMP (rgba->alpha, 0, 1));
return g_strdup_printf ("rgba(%d,%d,%d,%s)",
- (int)(0.5 + CLAMP (rgba->red, 0., 1.) * 255.),
- (int)(0.5 + CLAMP (rgba->green, 0., 1.) * 255.),
- (int)(0.5 + CLAMP (rgba->blue, 0., 1.) * 255.),
- alpha);
+ (int)(0.5 + CLAMP (rgba->red, 0., 1.) * 255.),
+ (int)(0.5 + CLAMP (rgba->green, 0., 1.) * 255.),
+ (int)(0.5 + CLAMP (rgba->blue, 0., 1.) * 255.),
+ alpha);
}
}
diff --git a/gdk/gdkrgba.h b/gdk/gdkrgba.h
index d0d1286..e5f2668 100644
--- a/gdk/gdkrgba.h
+++ b/gdk/gdkrgba.h
@@ -45,20 +45,19 @@ struct _GdkRGBA
#define GDK_TYPE_RGBA (gdk_rgba_get_type ())
-GdkRGBA * gdk_rgba_copy (const GdkRGBA *rgba);
-void gdk_rgba_free (GdkRGBA *rgba);
+GType gdk_rgba_get_type (void) G_GNUC_CONST;
-gboolean gdk_rgba_parse (GdkRGBA *rgba,
- const gchar *spec);
+GdkRGBA * gdk_rgba_copy (const GdkRGBA *rgba);
+void gdk_rgba_free (GdkRGBA *rgba);
-guint gdk_rgba_hash (gconstpointer p);
-gboolean gdk_rgba_equal (gconstpointer p1,
- gconstpointer p2);
+guint gdk_rgba_hash (gconstpointer p);
+gboolean gdk_rgba_equal (gconstpointer p1,
+ gconstpointer p2);
+gboolean gdk_rgba_parse (GdkRGBA *rgba,
+ const gchar *spec);
gchar * gdk_rgba_to_string (const GdkRGBA *rgba);
-GType gdk_rgba_get_type (void) G_GNUC_CONST;
-
G_END_DECLS
diff --git a/gdk/gdkwindow.c b/gdk/gdkwindow.c
index e53fdd0..af702a4 100644
--- a/gdk/gdkwindow.c
+++ b/gdk/gdkwindow.c
@@ -51,12 +51,12 @@
* @Short_description: Onscreen display areas in the target window system
* @Title: Windows
*
- * A #GdkWindow is a rectangular region on the screen. It's a low-level object,
- * used to implement high-level objects such as #GtkWidget and #GtkWindow on the
- * GTK+ level. A #GtkWindow is a toplevel window, the thing a user might think
- * of as a "window" with a titlebar and so on; a #GtkWindow may contain many
- * #GdkWindow<!-- -->s. For example, each #GtkButton has a #GdkWindow associated
- * with it.
+ * A #GdkWindow is a (usually) rectangular region on the screen.
+ * It's a low-level object, used to implement high-level objects such as
+ * #GtkWidget and #GtkWindow on the GTK+ level. A #GtkWindow is a toplevel
+ * window, the thing a user might think of as a "window" with a titlebar and
+ * so on; a #GtkWindow may contain many #GdkWindows. For example, each
+ * #GtkButton has a #GdkWindow associated with it.
*
* <refsect2 id="COMPOSITED-WINDOWS">
* <title>Composited Windows</title>
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
