Commit f95dceaa authored by Havoc Pennington's avatar Havoc Pennington Committed by Havoc Pennington
Browse files

fix these docs to reflect the current state of affairs

2001-02-20  Havoc Pennington  <hp@pobox.com>

	* gdk/tmpl/rgb.sgml: fix these docs to reflect the current state
	of affairs
parent 50b1ab41
2001-02-20 Havoc Pennington <hp@pobox.com>
* gdk/tmpl/rgb.sgml: fix these docs to reflect the current state
of affairs
2001-02-19 Havoc Pennington <hp@pobox.com>
* gdk/Makefile.am (SCAN_OPTIONS): add --deprecated-guards
......
......@@ -2,59 +2,23 @@
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.
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_pixbuf_render_to_drawable() uses GdkRGB in its implementation.
</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.
</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.
Setting it to 0 means that it always tries to use the default
......@@ -91,10 +55,10 @@ main (int argc, char *argv[])
guchar *pos;
gtk_init (&amp;argc, &amp;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);
gtk_widget_set_usize (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);
......@@ -139,32 +103,26 @@ on_darea_expose (GtkWidget *widget,
colors.</para></listitem>
</varlistentry>
<varlistentry>
<term>#GdkPixbuf and gdk_pixbuf_render_to_drawable()</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>
<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.
This function no longer does anything at all. It's completely useless
(and harmless).
</para>
<!-- ##### 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.
function, and likely the only one you will need to use.
</para>
<para>
......@@ -448,8 +406,11 @@ private colormap.
<!-- ##### 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.
Gets a "preferred visual" chosen by GdkRgb. In previous versions of
GDK, this was the only visual GdkRgb could use for rendering. In
current versions, it's simply the visual GdkRgb would have chosen as
the optimal one in those previous versions. GdkRgb can now render to
drawables with any visual.
</para>
@Returns: The #GdkVisual chosen by GdkRgb.
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment