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> 2001-02-19 Havoc Pennington <hp@pobox.com>
* gdk/Makefile.am (SCAN_OPTIONS): add --deprecated-guards * gdk/Makefile.am (SCAN_OPTIONS): add --deprecated-guards
......
...@@ -2,59 +2,23 @@ ...@@ -2,59 +2,23 @@
GdkRGB GdkRGB
<!-- ##### SECTION Short_Description ##### --> <!-- ##### SECTION Short_Description ##### -->
displays RGB images (as well as grayscale and colormapped) to renders RGB, grayscale, or indexed image data to a #GdkDrawable
the native window.
<!-- ##### SECTION Long_Description ##### --> <!-- ##### 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> <para>
You must call gdk_rgb_init() before using any GdkRgb functionality. If GdkRgb is a low-level module which renders RGB, grayscale, and indexed
you fail to do so, expect coredumps. All Gtk+ widgets that use GdkRgb colormap images to a #GdkDrawable. It does this as efficiently as
(including #GtkPreview) call gdk_rgb_init() in their class_init method. possible, handling issues such as colormaps, visuals, dithering,
Thus, if you use GdkRgb only indirectly, you don't need to worry temporary buffers, and so on. Most code should use the higher-level
about it. #GdkPixbuf features in place of this module; for example,
gdk_pixbuf_render_to_drawable() uses GdkRGB in its implementation.
</para> </para>
<para> <para>
GdkRgb tries to use the system default visual and colormap, but GdkRGB allocates a color cube to use when rendering images. You can
doesn't always succeed. Thus, you have to be prepared to install the set the threshold for installing colormaps with
visual and colormap generated by GdkRgb. The following code sequence gdk_rgb_set_min_colors(). The default is 5x5x5 (125). If a colorcube
(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
of this size or larger can be allocated in the default colormap, then 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 Setting it to 0 means that it always tries to use the default
...@@ -91,10 +55,10 @@ main (int argc, char *argv[]) ...@@ -91,10 +55,10 @@ main (int argc, char *argv[])
guchar *pos; guchar *pos;
gtk_init (&amp;argc, &amp;argv); gtk_init (&amp;argc, &amp;argv);
gdk_rgb_init ();
window = gtk_window_new (GTK_WINDOW_TOPLEVEL); window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
darea = gtk_drawing_area_new (); 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_container_add (GTK_CONTAINER (window), darea);
gtk_signal_connect (GTK_OBJECT (darea), "expose-event", gtk_signal_connect (GTK_OBJECT (darea), "expose-event",
GTK_SIGNAL_FUNC (on_darea_expose), NULL); GTK_SIGNAL_FUNC (on_darea_expose), NULL);
...@@ -139,32 +103,26 @@ on_darea_expose (GtkWidget *widget, ...@@ -139,32 +103,26 @@ on_darea_expose (GtkWidget *widget,
colors.</para></listitem> colors.</para></listitem>
</varlistentry> </varlistentry>
<varlistentry>
<term>#GdkPixbuf and gdk_pixbuf_render_to_drawable()</term>
<listitem><para>Higher-level image handling.</para></listitem>
</varlistentry>
</variablelist> </variablelist>
</para> </para>
<!-- ##### FUNCTION gdk_rgb_init ##### --> <!-- ##### FUNCTION gdk_rgb_init ##### -->
<para> <para>
Initializes GdkRgb statically. It may be called more than once with no This function no longer does anything at all. It's completely useless
ill effects. It must, however, be called before any other GdkRgb (and harmless).
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.
</para> </para>
<!-- ##### FUNCTION gdk_draw_rgb_image ##### --> <!-- ##### FUNCTION gdk_draw_rgb_image ##### -->
<para> <para>
Draws an RGB image in the drawable. This is the core GdkRgb 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 function, and likely the only one you will need to use.
initialization stuff.
</para> </para>
<para> <para>
...@@ -448,8 +406,11 @@ private colormap. ...@@ -448,8 +406,11 @@ private colormap.
<!-- ##### FUNCTION gdk_rgb_get_visual ##### --> <!-- ##### FUNCTION gdk_rgb_get_visual ##### -->
<para> <para>
Gets the visual chosen by GdkRgb. This visual and the corresponding Gets a "preferred visual" chosen by GdkRgb. In previous versions of
colormap should be used when creating windows that will be drawn in by GdkRgb. 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> </para>
@Returns: The #GdkVisual chosen by GdkRgb. @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