/* This file is part of GEGL.

 *

 * 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 3 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 GEGL; if not, see <http://www.gnu.org/licenses/>.

 *

 * Copyright 2006-2011 Øyvind Kolås <pippin@gimp.org>

 */

#ifndef __GEGL_TILE_SOURCE_H__

#define __GEGL_TILE_SOURCE_H__

#include <glib-object.h>

#include <babl/babl.h>

#include "gegl-tile.h"

/***

 * GeglTileSource is the very top classes of the tile/buffer handling of Gegl. It defines the generic

 * command mechanism to interact with a set of tiles. This classe is derived in GeglTileBackend and

 * GeglTileHandler.

 */

G_BEGIN_DECLS

#define GEGL_TYPE_TILE_SOURCE            (gegl_tile_source_get_type ())

#define GEGL_TILE_SOURCE(obj)            (G_TYPE_CHECK_INSTANCE_CAST ((obj), GEGL_TYPE_TILE_SOURCE, GeglTileSource))

#define GEGL_TILE_SOURCE_CLASS(klass)    (G_TYPE_CHECK_CLASS_CAST ((klass),  GEGL_TYPE_TILE_SOURCE, GeglTileSourceClass))

#define GEGL_IS_TILE_SOURCE(obj)         (G_TYPE_CHECK_INSTANCE_TYPE ((obj), GEGL_TYPE_TILE_SOURCE))

#define GEGL_IS_TILE_SOURCE_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass),  GEGL_TYPE_TILE_SOURCE))

#define GEGL_TILE_SOURCE_GET_CLASS(obj)  (G_TYPE_INSTANCE_GET_CLASS ((obj),  GEGL_TYPE_TILE_SOURCE, GeglTileSourceClass))

typedef gint GeglTileCommand;

struct _GeglTileSource

{

  GObject   parent_instance;

  gpointer  (*command)  (GeglTileSource  *gegl_tile_source,

                         GeglTileCommand  command,

                         gint             x,

                         gint             y,

                         gint             z,

                         gpointer         data);

  gpointer  padding[4];

};

struct _GeglTileSourceClass

{

  GObjectClass  parent_class;

  gpointer      padding[4];

};

GType      gegl_tile_source_get_type (void) G_GNUC_CONST;

/* All commands have the ability to pass commands to all tiles the handlers

 * add abstraction to the commands the documentaiton given here is valid

 * when the commands are issued to a full blown GeglBuffer instance.

 */

enum _GeglTileCommand

{

  GEGL_TILE_IDLE = 0,

  GEGL_TILE_SET,

  GEGL_TILE_GET,

  GEGL_TILE_IS_CACHED,

  GEGL_TILE_EXIST,

  GEGL_TILE_VOID,

  GEGL_TILE_FLUSH,

  GEGL_TILE_REFETCH,

  GEGL_TILE_REINIT,

  GEGL_TILE_LAST_COMMAND

};

#ifdef NOT_REALLY_COS_THIS_IS_MACROS

/* The functions documented below are actually macros, all using the command vfunc */

/**

 * gegl_tile_source_get_tile:

 * @source: a GeglTileSource *

 * @x: x coordinate

 * @y: y coordinate

 * @z: tile zoom level

 *

 * Get a GeglTile *from the buffer, mipmap tiles for levels z!=0 will be

 * created on the fly as needed, empty tiles returned are copy on write

 * and must be locked before written to, and unlocked afterwards.

 *

 * Returns: the tile at x,y,z or NULL if the tile could not be provided.

 */

GeglTile *gegl_tile_source_get_tile  (GeglTileSource *source,

                                      gint            x,

                                      gint            y,

                                      gint            z);

/**

 * gegl_tile_source_set_tile:

 * @source: a GeglTileSource *

 * @x: x coordinate

 * @y: y coordinate

 * @z: tile zoom level

 * @tile: a #GeglTile

 *

 * Set a GeglTile in *from the buffer.

 *

 * Returns: the TRUE if the set was successful.

 */

gboolean  gegl_tile_source_set_tile  (GeglTileSource *source,

                                      gint            x,

                                      gint            y,

                                      gint            z,

                                      GeglTile       *tile);

/**

 * gegl_tile_source_is_cached:

 * @source: a GeglTileSource *

 * @x: tile x coordinate

 * @y: tile y coordinate

 * @z: tile zoom level

 *

 * Checks if a tile is in cache and easily retrieved.

 */

gboolean  gegl_tile_source_is_cached (GeglTileSource *source,

                                      gint            x,

                                      gint            y,

                                      gint            z);

/**

 * gegl_tile_source_exist:

 * @source: a GeglTileSource *

 * @x: x coordinate

 * @y: y coordinate

 * @z: tile zoom level

 *

 * Checks if a tile exists, this check would not cause the tile to be swapped

 * in.

 */

gboolean  gegl_tile_source_exist     (GeglTileSource *source,

                                      gint            x,

                                      gint            y,

                                      gint            z);

/**

 * gegl_tile_source_reinit:

 * @source: a GeglTileSource *

 *

 * Causes all tiles in cache to be refetched.

 */

void      gegl_tile_source_reinit    (GeglTileSource *source);

/**

 * gegl_tile_source_void:

 * @source: a GeglTileSource *

 * @x: x coordinate

 * @y: y coordinate

 * @z: tile zoom level

 *

 * Causes all references to a tile to be removed.

 */

void      gegl_tile_source_void      (GeglTileSource *source,

                                      gint            x,

                                      gint            y,

                                      gint            z);

/*    INTERNAL API

 * gegl_tile_source_refetch:

 * @source: a GeglTileSource *

 * @x: x coordinate

 * @y: y coordinate

 * @z: tile zoom level

 *

 * A message used internally when watching external buffers to indicate that

 * a refresh of all data relating to the coordinates needs to be refetched.

 * Subsequent get calls should get new and valid data for the tile coordinates.

 */

void      gegl_tile_source_refetch   (GeglTileSource *source,

                                      gint            x,

                                      gint            y,

                                      gint            z);

/*   INTERNAL API

 * gegl_tile_source_idle:

 * @source: a GeglTileSource *

 *

 * Allow different parts of the buffer to do idle work (saving cached

 * data lazily, perhaps prefetching in the future?), monitoring for

 * changes or other tasks. Used internally by the buffer object.

 *

 * Returns: the TRUE if some work was done.

 */

gboolean  gegl_tile_source_idle      (GeglTileSource *source);

#endif

#define gegl_tile_source_command(source,cmd,x,y,z,tile)\

   (((GeglTileSource*)(source))->command(source,cmd,x,y,z,tile))

#define gegl_tile_source_set_tile(source,x,y,z,tile) \

   (gboolean)GPOINTER_TO_INT(gegl_tile_source_command(source,GEGL_TILE_SET,x,y,z,tile))

#define gegl_tile_source_get_tile(source,x,y,z) \

   (GeglTile*)gegl_tile_source_command(source,GEGL_TILE_GET,x,y,z,NULL)

#define gegl_tile_source_is_cached(source,x,y,z) \

   (gboolean)GPOINTER_TO_INT(gegl_tile_source_command(source,GEGL_TILE_IS_CACHED,x,y,z,NULL))

#define gegl_tile_source_exist(source,x,y,z) \

   (gboolean)GPOINTER_TO_INT(gegl_tile_source_command(source,GEGL_TILE_EXIST,x,y,z,NULL))

#define gegl_tile_source_void(source,x,y,z) \

   gegl_tile_source_command(source,GEGL_TILE_VOID,x,y,z,NULL)

#define gegl_tile_source_refetch(source,x,y,z) \

   gegl_tile_source_command(source,GEGL_TILE_REFETCH,x,y,z,NULL)

#define gegl_tile_source_reinit(source) \

   gegl_tile_source_command(source,GEGL_TILE_REINIT,0,0,0,NULL)

#define gegl_tile_source_idle(source) \

   (gboolean)GPOINTER_TO_INT(gegl_tile_source_command(source,GEGL_TILE_IDLE,0,0,0,NULL))

G_END_DECLS

#endif