GdkRGB
<!-- ##### SECTION Short_Description ##### -->
-displays RGB images (as well as grayscale and colormapped) to
-the native window.
+Renders RGB, grayscale, or indexed image data to a GdkDrawable
<!-- ##### SECTION Long_Description ##### -->
-<para>
-
-GdkRgb converts RGB, grayscale, and colormapped images into the native
-window pixel format and displays them. It takes care of colormaps,
-visuals, dithering, and management of the temporary buffers.
-
-</para>
-
-<para>
-You must call gdk_rgb_init() before using any GdkRgb functionality. If
-you fail to do so, expect coredumps. All Gtk+ widgets that use GdkRgb
-(including #GtkPreview) call gdk_rgb_init() in their class_init method.
-Thus, if you use GdkRgb only indirectly, you don't need to worry
-about it.
-</para>
-
-<para>
-GdkRgb tries to use the system default visual and colormap, but
-doesn't always succeed. Thus, you have to be prepared to install the
-visual and colormap generated by GdkRgb. The following code sequence
-(before any widgets are created) should work in most applications:
-</para>
-
-<informalexample>
-<programlisting>
- gdk_rgb_init ();
-
- gtk_widget_set_default_colormap (gdk_rgb_get_cmap ());
- gtk_widget_set_default_visual (gdk_rgb_get_visual ());
-</programlisting>
-</informalexample>
<para>
-You can also push the colormap and visual, but in general it doesn't
-work unless the push wraps the window creation call. If you wrap the
-push around a widget which is embedded in a window without the GdkRgb
-colormap and visual, it probably won't work, and is likely to cause
-colormap flashing, as well.
+GdkRGB is a low-level module which renders RGB, grayscale, and indexed
+colormap images to a #GdkDrawable. It does this as efficiently as
+possible, handling issues such as colormaps, visuals, dithering,
+temporary buffers, and so on. Most code should use the higher-level
+#GdkPixbuf features in place of this module; for example,
+gdk_draw_pixbuf() uses GdkRGB in its implementation.
</para>
<para>
-On 8-bit systems, the colormaps used by Imlib and GdkRgb may
-conflict. There is no good general solution to this other than phasing
-out the dependence on Imlib.
-</para>
-
-<para>
-You can set the threshold for installing colormaps with
-gdk_rgb_set_min_colors (). The default is 5x5x5 (125). If a colorcube
+GdkRGB allocates a color cube to use when rendering images. You can
+set the threshold for installing colormaps with
+gdk_rgb_set_min_colors(). The default is 5x5x5 (125). If a colorcube
of this size or larger can be allocated in the default colormap, then
-that's done. Otherwise, GdkRgb creates its own private colormap.
+that's done. Otherwise, GdkRGB creates its own private colormap.
Setting it to 0 means that it always tries to use the default
colormap, and setting it to 216 means that it always creates a private
one if it cannot allocate the 6x6x6 colormap in the default. If you
always want a private colormap (to avoid consuming too many colormap
-entries for other apps, say), you can use gdk_rgb_set_install(TRUE).
+entries for other apps, say), you can use
+<literal>gdk_rgb_set_install(TRUE)</literal>.
Setting the value greater than 216 exercises a bug in older versions
-of GdkRgb. Note, however, that setting it to 0 doesn't let you get
+of GdkRGB. Note, however, that setting it to 0 doesn't let you get
away with ignoring the colormap and visual - a colormap is always
created in grayscale and direct color modes, and the visual is changed
in cases where a "better" visual than the default is available.
</para>
+<para>
+If GDK is built with the Sun mediaLib library, the GdkRGB functions are
+accelerated using mediaLib, which provides hardware acceleration on Intel,
+AMD, and Sparc chipsets. If desired, mediaLib support can be turned off
+by setting the GDK_DISABLE_MEDIALIB environment variable.
+</para>
+
<example>
-<title>A simple example program using GdkRGB.</title>
+<title>A simple example program using GdkRGB</title>
<programlisting>
-#include <gtk/gtk.h>
+#include <gtk/gtk.h>
-#define IMAGE_WIDTH 256
-#define IMAGE_HEIGHT 256
+#define IMAGE_WIDTH 256
+#define IMAGE_HEIGHT 256
guchar rgbbuf[IMAGE_WIDTH * IMAGE_HEIGHT * 3];
guchar *pos;
gtk_init (&argc, &argv);
- gdk_rgb_init ();
+
window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
- darea = gtk_drawing_area_new ();
- gtk_drawing_area_size (GTK_DRAWING_AREA (darea), IMAGE_WIDTH, IMAGE_HEIGHT);
+ darea = gtk_drawing_area_new (<!-- -->);
+ gtk_widget_set_size_request (darea, IMAGE_WIDTH, IMAGE_HEIGHT);
gtk_container_add (GTK_CONTAINER (window), darea);
gtk_signal_connect (GTK_OBJECT (darea), "expose-event",
GTK_SIGNAL_FUNC (on_darea_expose), NULL);
/* Set up the RGB buffer. */
pos = rgbbuf;
- for (y = 0; y < IMAGE_HEIGHT; y++)
+ for (y = 0; y < IMAGE_HEIGHT; y++)
{
- for (x = 0; x < IMAGE_WIDTH; x++)
+ for (x = 0; x < IMAGE_WIDTH; x++)
{
*pos++ = x - x % 32; /* Red. */
*pos++ = (x / 32) * 4 + y - y % 32; /* Green. */
}
}
- gtk_main ();
+ gtk_main (<!-- -->);
return 0;
}
gdk_draw_rgb_image (widget->window, widget->style->fg_gc[GTK_STATE_NORMAL],
0, 0, IMAGE_WIDTH, IMAGE_HEIGHT,
GDK_RGB_DITHER_MAX, rgbbuf, IMAGE_WIDTH * 3);
+
+ return TRUE;
}
</programlisting>
</example>
<varlistentry>
<term>#GdkColor</term>
-<listitem><para>The underlying Gdk mechanism for allocating
+<listitem><para>The underlying GDK mechanism for allocating
colors.</para></listitem>
</varlistentry>
+<varlistentry>
+<term>#GdkPixbuf and gdk_draw_pixbuf()</term>
+<listitem><para>Higher-level image handling.</para></listitem>
+</varlistentry>
+
</variablelist>
</para>
-<!-- ##### FUNCTION gdk_rgb_init ##### -->
-<para>
-Initializes GdkRgb statically. It may be called more than once with no
-ill effects. It must, however, be called before any other GdkRgb
-operations are performed.
-</para>
+<!-- ##### SECTION Stability_Level ##### -->
-<para>
-The GdkRgb "context" is allocated statically. Thus, GdkRgb may be used
-to drive only one visual in any given application. GdkRgb
-automatically selects a best visual and sets its own colormap, if
-necessary. gdk_rgb_get_visual() and gdk_rgb_get_cmap () retrieve
-the chosen visual and colormap, respectively.
-</para>
+<!-- ##### SECTION Image ##### -->
<!-- ##### FUNCTION gdk_draw_rgb_image ##### -->
<para>
-Draws an RGB image in the drawable. This is the core GdkRgb
-function, and likely the only one you will need to use other than the
-initialization stuff.
+Draws an RGB image in the drawable. This is the core GdkRGB
+function, and likely the only one you will need to use.
</para>
<para>
</para>
@drawable: The #GdkDrawable to draw in (usually a #GdkWindow).
-@gc: The graphics context (all Gdk drawing operations require one; its
+@gc: The graphics context (all GDK drawing operations require one; its
contents are ignored).
@x: The x coordinate of the top-left corner in the drawable.
@y: The y coordinate of the top-left corner in the drawable.
<!-- ##### ENUM GdkRgbDither ##### -->
<para>
-
-Selects whether or not GdkRgb applies dithering
-to the image on display. There are three values:
-</para>
-
-<itemizedlist>
-
-<listitem>
-<para>
-%GDK_RGB_DITHER_NONE: Never use dithering.
+Selects whether or not GdkRGB applies dithering
+to the image on display.
</para>
-</listitem>
-<listitem>
<para>
-%GDK_RGB_DITHER_NORMAL: Use dithering in 8 bits per pixel (and below)
-only.
-</para>
-</listitem>
-
-<listitem>
-<para>
-%GDK_RGB_DITHER_MAX: Use dithering in 16 bits per pixel and below.
-</para>
-</listitem>
-
-</itemizedlist>
-
-<para>
-Since GdkRgb currently only handles images with 8 bits per component,
+Since GdkRGB currently only handles images with 8 bits per component,
dithering on 24 bit per pixel displays is a moot point.
</para>
-@GDK_RGB_DITHER_NONE:
-@GDK_RGB_DITHER_NORMAL:
-@GDK_RGB_DITHER_MAX:
+@GDK_RGB_DITHER_NONE: Never use dithering.
+@GDK_RGB_DITHER_NORMAL: Use dithering in 8 bits per pixel (and below)
+only.
+@GDK_RGB_DITHER_MAX: Use dithering in 16 bits per pixel and below.
<!-- ##### FUNCTION gdk_rgb_cmap_new ##### -->
<para>
colors. This is used only for gdk_draw_indexed_image().
</para>
-@colors:
-@n_colors:
-
-<!-- ##### FUNCTION gdk_rgb_gc_set_foreground ##### -->
-<para>
-Sets the foreground color in @gc to the specified color (or the
-closest approximation, in the case of limited visuals).
-</para>
-
-@gc: The #GdkGC to modify.
-@rgb: The color, represented as a 0xRRGGBB integer value.
-
-
-<!-- ##### FUNCTION gdk_rgb_gc_set_background ##### -->
-<para>
-Sets the background color in @gc to the specified color (or the
-closest approximation, in the case of limited visuals).
-</para>
-
-@gc: The #GdkGC to modify.
-@rgb: The color, represented as a 0xRRGGBB integer value.
-
-
-<!-- ##### FUNCTION gdk_rgb_xpixel_from_rgb ##### -->
-<para>
-Finds the X pixel closest in color to the @rgb color specified. This
-value may be used to set the <structfield>pixel</structfield> field of
-a #GdkColor struct.
-</para>
-
-@rgb: The color, represented as a 0xRRGGBB integer value.
-@Returns: The X pixel value.
-
+@colors: The colors, represented as 0xRRGGBB integer values.
+@n_colors: The number of colors in the cmap.
<!-- ##### FUNCTION gdk_rgb_find_color ##### -->
<para>
<!-- ##### FUNCTION gdk_rgb_set_install ##### -->
<para>
-If @install is TRUE, directs GdkRgb to always install a new "private"
+If @install is %TRUE, directs GdkRGB to always install a new "private"
colormap rather than trying to find a best fit with the colors already
-allocated. Ordinarily, GdkRgb will install a colormap only if a
+allocated. Ordinarily, GdkRGB will install a colormap only if a
sufficient cube cannot be allocated.
</para>
but also leads to the dreaded "colormap flashing" effect.
</para>
-@install: TRUE to set install mode.
+@install: %TRUE to set install mode.
<!-- ##### FUNCTION gdk_rgb_set_min_colors ##### -->
<para>
Sets the minimum number of colors for the color cube. Generally,
-GdkRgb tries to allocate the largest color cube it can. If it can't
+GdkRGB tries to allocate the largest color cube it can. If it can't
allocate a color cube at least as large as @min_colors, it installs a
private colormap.
</para>
<!-- ##### FUNCTION gdk_rgb_get_visual ##### -->
<para>
-Gets the visual chosen by GdkRgb. This visual and the corresponding
-colormap should be used when creating windows that will be drawn in by GdkRgb.
</para>
-@Returns: The #GdkVisual chosen by GdkRgb.
+@void:
+@Returns:
<!-- ##### FUNCTION gdk_rgb_get_colormap ##### -->
</para>
+@void:
@Returns:
-<!-- ##### MACRO gdk_rgb_get_cmap ##### -->
+<!-- ##### FUNCTION gdk_rgb_ditherable ##### -->
<para>
-Gets the colormap set by GdkRgb. This colormap and the corresponding
-visual should be used when creating windows that will be drawn in by GdkRgb.
+Determines whether the preferred visual is ditherable. This function may be
+useful for presenting a user interface choice to the user about which
+dither mode is desired; if the display is not ditherable, it may make
+sense to gray out or hide the corresponding UI widget.
</para>
-@Returns: The #GdkColormap set by GdkRgb.
+@void:
+@Returns: %TRUE if the preferred visual is ditherable.
-<!-- ##### FUNCTION gdk_rgb_ditherable ##### -->
+<!-- ##### FUNCTION gdk_rgb_colormap_ditherable ##### -->
<para>
-Determine whether the visual is ditherable. This function may be
-useful for presenting a user interface choice to the user about which
-dither mode is desired; if the display is not ditherable, it may make
-sense to gray out or hide the corresponding UI widget.
+Determines whether the visual associated with @cmap is ditherable. This
+function may be useful for presenting a user interface choice to the user
+about which dither mode is desired; if the display is not ditherable, it may
+make sense to gray out or hide the corresponding UI widget.
</para>
-@Returns: TRUE if the visual is ditherable.
+@cmap: a #GdkColormap
+@Returns: %TRUE if the visual associated with @cmap is ditherable.
<!-- ##### FUNCTION gdk_rgb_set_verbose ##### -->
Sets the "verbose" flag. This is generally only useful for debugging.
</para>
-@verbose: TRUE if verbose messages are desired.
+@verbose: %TRUE if verbose messages are desired.
projects / ~andy / gtk / blobdiff