diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog index a094c3ab41..82615e1ded 100644 --- a/docs/reference/ChangeLog +++ b/docs/reference/ChangeLog @@ -1,3 +1,8 @@ +2001-02-20 Havoc Pennington + + * gdk/tmpl/rgb.sgml: fix these docs to reflect the current state + of affairs + 2001-02-19 Havoc Pennington * gdk/Makefile.am (SCAN_OPTIONS): add --deprecated-guards diff --git a/docs/reference/gdk/tmpl/rgb.sgml b/docs/reference/gdk/tmpl/rgb.sgml index c60cde24ac..a62e96e842 100644 --- a/docs/reference/gdk/tmpl/rgb.sgml +++ b/docs/reference/gdk/tmpl/rgb.sgml @@ -2,59 +2,23 @@ GdkRGB -displays RGB images (as well as grayscale and colormapped) to -the native window. +renders RGB, grayscale, or indexed image data to a #GdkDrawable + - -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. - +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. -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 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: - - - - - gdk_rgb_init (); - - gtk_widget_set_default_colormap (gdk_rgb_get_cmap ()); - gtk_widget_set_default_visual (gdk_rgb_get_visual ()); - - - - -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. - - - -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. - - - -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 (&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); + 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. + +#GdkPixbuf and gdk_pixbuf_render_to_drawable() +Higher-level image handling. + + -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. +This function no longer does anything at all. It's completely useless +(and harmless). - -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. - - - 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. @@ -448,8 +406,11 @@ private colormap. -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. @Returns: The #GdkVisual chosen by GdkRgb.