/* $Id: visual.hg,v 1.4 2006/04/12 11:11:24 murrayc Exp $ */

/* bitmap.h
 *
 * Copyright (C) 1998-2002 The gtkmm Development Team
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or (at your option) any later version.
 *
 * 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
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free
 * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
 */

#include <glibmm/object.h>
#include <gdkmm/screen.h>
#include <gdk/gdk.h>

_DEFS(gdkmm,gdk)
_PINCLUDE(glibmm/private/object_p.h)


namespace Gdk
{

class Screen;

_WRAP_ENUM(VisualType, GdkVisualType)

/** A Gdk::Visual describes a particular video hardware display format.
 * It includes information about the number of bits used for each color, the way the bits are translated into an RGB value
 * for display, and the way the bits are stored in memory. For example, a piece of display hardware might support 24-bit
 * color, 16-bit color, or 8-bit color; meaning 24/16/8-bit pixel sizes. For a given pixel size, pixels can be in different
 * formats; for example the "red" element of an RGB pixel may be in the top 8 bits of the pixel, or may be in the lower 4
 * bits.
 *
 * Usually you can avoid thinking about visuals in GTK+. Visuals are useful to interpret the contents of a GdkImage, but
 * you should avoid Gdk::Image precisely because its contents depend on the display hardware; use Gdk::Pixbuf instead, for
 * all but the most low-level purposes. Also, anytime you provide a Gdk::Colormap, the visual is implied as part of the
 * colormap (Gdk::Colormap::get_visual()), so you won't have to provide a visual in addition.
 *
 * There are several standard visuals. The visual returned by get_system() is the system's default visual. get_visual()
 * returns the visual most suited to displaying full-color image data. If you use the calls in Gdk::RGB, you should create
 * your windows using this visual (and the colormap returned by Gdk::Rgb::get_colormap()).
 *
 * A number of methods are provided for determining the "best" available visual. For the purposes of making this
 * determination, higher bit depths are considered better, and for visuals of the same bit depth, GDK_VISUAL_PSEUDO_COLOR
 * is preferred at 8bpp, otherwise, the visual types are ranked in the order of (highest to lowest) GDK_VISUAL_DIRECT_COLOR,
 * GDK_VISUAL_TRUE_COLOR, GDK_VISUAL_PSEUDO_COLOR, GDK_VISUAL_STATIC_COLOR, GDK_VISUAL_GRAYSCALE, then
 * GDK_VISUAL_STATIC_GRAY.
 */
class Visual : public Glib::Object
{
  _CLASS_GOBJECT(Visual,GdkVisual,GDK_VISUAL,Glib::Object,GObject)
protected:

  _CTOR_DEFAULT

public:
   _WRAP_METHOD(static Glib::RefPtr<Visual> get_system(), gdk_visual_get_system, refreturn)
   _WRAP_METHOD(static Glib::RefPtr<Visual> get_best(), gdk_visual_get_best, refreturn)
   _WRAP_METHOD(static Glib::RefPtr<Visual> get_best(int depth), gdk_visual_get_best_with_depth, refreturn)
   _WRAP_METHOD(static Glib::RefPtr<Visual> get_best(VisualType visual_type), gdk_visual_get_best_with_type, refreturn)
   _WRAP_METHOD(static Glib::RefPtr<Visual> get_best(int depth, VisualType visual_type), gdk_visual_get_best_with_both, refreturn)

   _WRAP_METHOD(static int get_best_depth(), gdk_visual_get_best_depth)
   _WRAP_METHOD(static VisualType get_best_type(), gdk_visual_get_best_type)

   _WRAP_METHOD(Glib::RefPtr<Screen> get_screen(), gdk_visual_get_screen, refreturn)
   _WRAP_METHOD(Glib::RefPtr<const Screen> get_screen() const, gdk_visual_get_screen, refreturn, constversion)
};

} //namespace Gdk

