path: root/pig/pig-picture.c

/* PIG - The GIMP Drawing Kit
 * Copyright (C) 2010 Benjamin Otte <otte@gnome.org>
 *
 * 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 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., 59 Temple Place - Suite 330,
 * Boston, MA 02111-1307, USA.
 */

#include "config.h"

#include "pig-picture.h"

#include <cairo-gobject.h>
#include <glib/gi18n-lib.h>

#include "pig-marshal-private.h"

struct _PigPicturePrivate {
  int width;
  int height;
};

G_DEFINE_ABSTRACT_TYPE (PigPicture, pig_picture, G_TYPE_OBJECT)

enum {
  PROP_0,
  PROP_WIDTH,
  PROP_HEIGHT
};

enum {
  RESIZED,
  CHANGED,
  LAST_SIGNAL
};

static guint signals [LAST_SIGNAL] = { 0 };

/**
 * SECTION:picture
 * @Short_Description: pixel areas to display
 * @Title: PigPicture
 * @See_also: #PigMotionPicture
 *
 * A #PigPicture is used to represent a pixel area of a specific size.
 * Its main job is being the interface between applications that want
 * to display pictures without a lot of work and people that want to
 * provide pictures that can be rendered.
 *
 * Pictures can resize themselves and change their contents over time.
 * If you need to react to updates, you should connect to the
 * PigPicture::resized and PigPicture::changed signals.
 *
 * A lot of #PigPicture subclasses require a running main loop, so if
 * you want to use #PigPicture without a main loop, you need to make
 * sure that it actually works.
 *
 * #PigPicture is meant to replace #GdkPixbuf.
 */

/**
 * PigPicture:
 *
 * This object represents a picture. All object members are private
 * and must not be accessed.
 */

/**
 * PigPictureClass:
 * @ref_surface: Get a reference to a #cairo_surface_t that represents
 *   the currently displayed surface. For more details, see
 *   pig_picture_ref_surface(), which will call this function. If you
 *   don't implement this function, the default implementation will
 *   call the @draw function, and you must implement that one.
 * @draw: Draw the current picture to the provided #cairo_t. For more
 *   details, see pig_picture_draw(), which will call this function. If
 *   you do not implement it, the default implementation will call the
 *   @ref_surface function, and you must implement that one.
 *
 * The class structure for #PigPicture.
 */

static void
pig_picture_get_property (GObject    *object,
                          guint       prop_id,
                          GValue     *value,
                          GParamSpec *pspec)
{
  PigPicture *picture = PIG_PICTURE (object);
  PigPicturePrivate *priv = picture->priv;

  switch (prop_id)
    {
    case PROP_WIDTH:
      g_value_set_int (value, priv->width);
      break;
    case PROP_HEIGHT:
      g_value_set_int (value, priv->height);
      break;
    default:
      G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
      break;
    }
}

static cairo_surface_t *
pig_picture_fallback_ref_surface (PigPicture *picture)
{
  PigPicturePrivate *priv = picture->priv;
  cairo_surface_t *surface;
  cairo_t *cr;

  surface = cairo_image_surface_create (CAIRO_FORMAT_ARGB32,
                                        priv->width,
                                        priv->height);
  cr = cairo_create (surface);

  pig_picture_draw (picture, cr);

  cairo_destroy (cr);

  return surface;
}

static void
pig_picture_fallback_draw (PigPicture *picture,
                           cairo_t    *cr)
{
  cairo_surface_t *surface;

  surface = pig_picture_ref_surface (picture);
  cairo_set_source_surface (cr, surface, 0, 0);
  cairo_surface_destroy (surface);

  cairo_paint (cr);
}

static void
pig_picture_class_init (PigPictureClass *klass)
{
  GObjectClass *object_class = G_OBJECT_CLASS (klass);

  object_class->get_property = pig_picture_get_property;

  klass->ref_surface = pig_picture_fallback_ref_surface;
  klass->draw = pig_picture_fallback_draw;

  /**
   * PigPicture:width:
   *
   * Number of pixels in the x direction.
   *
   * Since: 3.2
   */
  g_object_class_install_property (object_class,
                                   PROP_WIDTH,
                                   g_param_spec_int ("width",
                                                     _("width"),
                                                     _("Number of pixels in x direction"),
                                                     0, G_MAXINT, 0,
                                                     G_PARAM_READABLE | G_PARAM_STATIC_STRINGS));

  /**
   * PigPicture:height:
   *
   * Number of pixels in the y direction.
   *
   * Since: 3.2
   */
  g_object_class_install_property (object_class,
                                   PROP_HEIGHT,
                                   g_param_spec_int ("height",
                                                     _("height"),
                                                     _("Number of pixels in y direction"),
                                                     0, G_MAXINT, 0,
                                                     G_PARAM_READABLE | G_PARAM_STATIC_STRINGS));

  /**
   * PigPicture::changed:
   * @picture: the #PigPicture that changed.
   * @region: the region that was changed
   *
   * The ::changed signal is emitted when the contents of a @picture
   * have changed and a redraw of parts of the @picture are necessary.
   * The given @region specifies the area that has changed. It is valid
   * if @region is larger than the size of the @picture. This will happen
   * in particular when emitting this signal after @picture was resized
   * to a smaller size.
   */
  signals[CHANGED] =
    g_signal_new (g_intern_static_string ("changed"),
                  G_TYPE_FROM_CLASS (object_class),
                  G_SIGNAL_RUN_LAST,
                  0, NULL, NULL,
                  _pig_marshal_VOID__BOXED,
                  G_TYPE_NONE, 1, CAIRO_GOBJECT_TYPE_REGION);

  /**
   * PigPicture::resized:
   * @picture: the #PigPicture that changed size
   *
   * The ::resize signal is emitted when the width or height of a 
   * @picture has changed. This  and a redraw of parts of the
   * @picture are necessary.
   * After the emission of this signal, a #PigPicture::changed
   * signal will be emitted, so it might not be necessary to connect
   * to both signals.
   */
  signals[RESIZED] =
    g_signal_new (g_intern_static_string ("resized"),
                  G_TYPE_FROM_CLASS (object_class),
                  G_SIGNAL_RUN_LAST,
                  0, NULL, NULL,
                  _pig_marshal_VOID__VOID,
                  G_TYPE_NONE, 0);

  g_type_class_add_private (klass, sizeof (PigPicturePrivate));
}

static void
pig_picture_init (PigPicture *picture)
{
  picture->priv = G_TYPE_INSTANCE_GET_PRIVATE (picture,
                                               PIG_TYPE_PICTURE,
                                               PigPicturePrivate);
}

/**
 * pig_picture_get_width:
 * @picture: the picture
 *
 * Gets the width of the @picture. That is the number of pixels in the
 * X direction. Note that the width may be 0 in certain cases, like
 * when a picture hasn't finished loading from a file yet.
 *
 * Returns: The width of @picture
 **/
int
pig_picture_get_width (PigPicture *picture)
{
  g_return_val_if_fail (PIG_IS_PICTURE (picture), 0);

  return picture->priv->width;
}

/**
 * pig_picture_get_height:
 * @picture: the picture
 *
 * Gets the height of the @picture. That is the number of pixels in the
 * Y direction. Note that the width may be 0 in certain cases, like
 * when a picture hasn't finished loading from a file yet.
 *
 * Returns: The height of @picture
 **/
int
pig_picture_get_height (PigPicture *picture)
{
  g_return_val_if_fail (PIG_IS_PICTURE (picture), 0);

  return picture->priv->height;
}

/**
 * pig_picture_ref_surface:
 * @picture: the picture to get the surface from
 *
 * Gets a #cairo_surface_t representing the @picture. This function is
 * useful when you don't just want to draw @picture, but do more
 * sophisticated things, like use it in a cairo_mask() call. You must not
 * modify the returned surface.
 * If you just want to draw the @picture, calling pig_picture_draw() is
 *
 * Returns: (transfer full): A surface representing @picture. The surface
 *   remains a valid representation of @picture's contents until the next
 *   time the PigPicture::changed signal is emitted. Use
 *   cairo_surface_destroy() to free the returned surface.
 **/
cairo_surface_t *
pig_picture_ref_surface (PigPicture *picture)
{
  PigPictureClass *picture_class;

  g_return_val_if_fail (PIG_IS_PICTURE (picture), NULL);

  picture_class = PIG_PICTURE_GET_CLASS (picture);

  return picture_class->ref_surface (picture);
}

/**
 * pig_picture_draw:
 * @picture: the picture to draw
 * @cr: the cairo context to draw to
 *
 * Draws the given @picture to the given cairo context. The cairo context
 * should be set to default values for everything but the source and the
 * matrix. Otherwise the results are undefined.
 **/
void
pig_picture_draw (PigPicture *picture,
                  cairo_t    *cr)
{
  PigPictureClass *picture_class;

  g_return_if_fail (PIG_IS_PICTURE (picture));

  picture_class = PIG_PICTURE_GET_CLASS (picture);

  cairo_save (cr);

  picture_class->draw (picture, cr);

  cairo_restore (cr);
}

/**
 * pig_picture_resized:
 * @picture: the picture that was resized
 * @new_width: the new width
 * @new_height: the new height
 *
 * Resizes the picture to the given size and emits the
 * PigPicture::resized signal to indicate that change.
 * It will also emit the PigPicture::changed signal for the whole
 * picture.
 *
 * This function should be considered protected and only be called
 * by subclass implementations of #PigPicture.
 **/
void
pig_picture_resized (PigPicture *picture,
                     int         new_width,
                     int         new_height)
{
  cairo_rectangle_int_t resized_rect;
  PigPicturePrivate *priv;
  
  g_return_if_fail (PIG_IS_PICTURE (picture));
  g_return_if_fail (new_width >= 0);
  g_return_if_fail (new_height >= 0);

  priv = picture->priv;

  resized_rect.x = 0;
  resized_rect.y = 0;
  resized_rect.width = MAX (priv->width, new_width);
  resized_rect.height = MAX (priv->height, new_height);

  pig_picture_resized_unchanged (picture, new_width, new_height);

  pig_picture_changed_rectangle (picture, &resized_rect);
}

/**
 * pig_picture_resized_unchanged:
 * @picture: the picture to be resized
 * @new_width: the new width for @picture
 * @new_height: the new height of @picture
 *
 * Resizes the picture to the given size and emits the
 * PigPicture::resized signal to indicate that change.
 * Does not emit the PigPicture::changed signal. You must do that
 * manually, because the API guarantees that this signal is emitted
 * for changes to the picture. Keep in mind that the changed area may
 * be larger than the new size of the @picture when you resize it to
 * become smaller.
 * Unless you do know exactly what you are doing, you should probably
 * use pig_picture_resized() instead.
 *
 * This function should be considered protected and only be called
 * by subclass implementations of #PigPicture.
 **/
void
pig_picture_resized_unchanged (PigPicture *picture,
                               int         new_width,
                               int         new_height)
{
  int old_width, old_height;
  GObject *object;
  PigPicturePrivate *priv;
  
  g_return_if_fail (PIG_IS_PICTURE (picture));
  g_return_if_fail (new_width >= 0);
  g_return_if_fail (new_height >= 0);

  object = G_OBJECT (picture);
  priv = picture->priv;

  old_width = priv->width;
  old_height = priv->height;

  if (old_width == new_width && old_height == new_height)
    return;

  g_object_freeze_notify (object);

  priv->width = new_width;
  g_object_notify (object, "width");
  priv->height = new_height;
  g_object_notify (object, "height");

  g_object_thaw_notify (object);

  g_signal_emit (picture, signals[RESIZED], 0);
}

/**
 * pig_picture_changed:
 * @picture: the picture that changed
 *
 * Emits the PigPicture::changed signal for the whole picture.
 *
 * This function should be considered protected and only be called
 * by subclass implementations of #PigPicture.
 **/
void
pig_picture_changed (PigPicture *picture)
{
  PigPicturePrivate *priv;
  cairo_rectangle_int_t rect;
  
  g_return_if_fail (PIG_IS_PICTURE (picture));

  priv = picture->priv;

  rect.x = 0;
  rect.y = 0;
  rect.width = priv->width;
  rect.height = priv->height;

  pig_picture_changed_rectangle (picture, &rect);
}

/**
 * pig_picture_changed_rectangle:
 * @picture: the picture that changed
 * @rect: the rectangle describing the region that changed
 *
 * Emits the PigPicture::changed signal for the region specified in @rect.
 * It is valid for @rect to describe regions outside of the size of
 * @picture, it will not be automatically clipped.
 *
 * This function should be considered protected and only be called
 * by subclass implementations of #PigPicture.
 **/
void
pig_picture_changed_rectangle (PigPicture                  *picture,
                               const cairo_rectangle_int_t *rect)
{
  cairo_region_t *region;

  g_return_if_fail (PIG_IS_PICTURE (picture));

  region = cairo_region_create_rectangle (rect);

  pig_picture_changed_region (picture, region);

  cairo_region_destroy (region);
}

/**
 * pig_picture_changed_region:
 * @picture: the picture that changed
 * @region: the region that changed
 *
 * Emits the PigPicture::changed signal for the given @region.
 * It is valid for @region to describe areas outside of the size of
 * @picture, it will not be automatically clipped.
 *
 * This function should be considered protected and only be called
 * by subclass implementations of #PigPicture.
 **/
void
pig_picture_changed_region (PigPicture           *picture,
                            const cairo_region_t *region)
{
  g_return_if_fail (PIG_IS_PICTURE (picture));
  g_return_if_fail (region != NULL);

  g_signal_emit (picture, signals[CHANGED], 0, region);
}