GEGL Operation API

gegl-operation.h
/* This file is part of GEGL
 *
 * GEGL 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.
 *
 * GEGL 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 <https://www.gnu.org/licenses/>.
 *
 * Copyright 2003 Calvin Williamson
 *           2005-2008 Øyvind Kolås
 */

#ifndef __GEGL_OPERATION_H__
#define __GEGL_OPERATION_H__

#include <glib-object.h>
#include <babl/babl.h>


#include "gegl-buffer.h"
#include "opencl/gegl-cl.h"

G_BEGIN_DECLS

#define GEGL_OPERATION_CLASS(klass)    (G_TYPE_CHECK_CLASS_CAST ((klass),  GEGL_TYPE_OPERATION, GeglOperationClass))
#define GEGL_IS_OPERATION_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass),  GEGL_TYPE_OPERATION))
#define GEGL_OPERATION_GET_CLASS(obj)  (G_TYPE_INSTANCE_GET_CLASS ((obj),  GEGL_TYPE_OPERATION, GeglOperationClass))
/* The rest is in gegl-types.h */

typedef struct _GeglOperationClass   GeglOperationClass;
typedef struct _GeglOperationPrivate GeglOperationPrivate;

struct _GeglOperation
{
  GObject parent_instance;

  /*< private >*/
  GeglNode *node;  /* the node that this operation object is communicated
                      with through */
};


/***
 * GeglOperation:
 *
 * All the image processing code in GEGL is implemented as GeglOperations,
 * GEGL operations are implemented as GObject with a convenience API called
 * chanting that abstracts away the boiler plater needed to generate introspectable
 * named properties of different types.
 *
 * Most types of operations like: filters, composers, sources, sinks, point
 * operations, compositing operations, and spatial operations with fixed
 * neighbourhoods. These base classes build on top of the GeglOperationsClass:
 *
 * See <a href='gegl-plugin.h.html'>gegl-plugin.h</a> for details.
 */

/* the level at which is being operated is stored in the context,
*/

struct _GeglOperationClass
{
  GObjectClass    parent_class;

  const gchar    *name;        /* name(string) used to create/identify
                                  this type of operation in GEGL, must be
                                  set through gegl_operation_class_set_key(s) */
  const gchar    *compat_name; /* allows specifying an alias that the op is
                                  also known as, must be set through
                                  gegl_operation_class_set_key(s) */
  GHashTable     *keys;        /* hashtable used for storing meta-data about an op */

  guint           no_cache      :1;  /* do not create a cache for this operation
                                        (deprecated for "cache_policy") */
  guint           opencl_support:1;
  guint           want_in_place:1; /* if possible to use for in-place
                                      processing, making output buffer =
                                      input buffer.
                                      */
  guint           threaded:1;  /* do threaded processing if possible,
                                  some base classes have special logic
                                  to accelerate rendering; this allows opting in/out
                                  in the sub-classes of these.
                                */
  guint           cache_policy:2; /* cache policy for this operation */
  guint64         bit_pad:58;

  /* attach this operation with a GeglNode, override this if you are creating a
   * GeglGraph, it is already defined for Filters/Sources/Composers.
   */
  void          (*attach)                    (GeglOperation *operation);

  /* Initialize the operation, prepare is called when all properties are
   * known but before processing will begin. Prepare will be invoked one
   * or multiple times prior to processing.
   */
  void          (*prepare)                   (GeglOperation *operation);

  /* The bounding rectangle for the data that is defined by this op.
   */
  GeglRectangle (*get_bounding_box)          (GeglOperation *operation);

  /* The output region that is made invalid by a change in the input_roi
   * rectangle of the buffer passed in on the pad input_pad. Defaults to
   * returning the input_roi.
   */
  GeglRectangle (*get_invalidated_by_change) (GeglOperation       *operation,
                                              const gchar         *input_pad,
                                              const GeglRectangle *input_roi);

  /* The rectangle needed to be correctly computed in a buffer on the named
   * input_pad, for a given region of interest. Defaults to return the
   * output_roi.
   */
  GeglRectangle (*get_required_for_output)   (GeglOperation       *operation,
                                              const gchar         *input_pad,
                                              const GeglRectangle *output_roi);

  /* The rectangular area that should be processed in one go, by default if not
   * defined the output roi would be returned. This is useful for file loaders
   * and operations like contrast stretching which is a point operation but we
   * need the parameters as the minimum/maximum values in the entire input buffer.
   */
  GeglRectangle (*get_cached_region)         (GeglOperation       *operation,
                                              const GeglRectangle *output_roi);

  /* Compute the rectangular region output roi for the specified output_pad.
   * For operations that are sinks (have no output pads), roi is the rectangle
   * to consume and the output_pad argument is to be ignored.
   */
  gboolean      (*process)                   (GeglOperation        *operation,
                                              GeglOperationContext *context,
                                              const gchar          *output_pad,
                                              const GeglRectangle  *roi,
                                              gint                  level);

  /* The node providing data for a specific location within the operations
   * output. The node is responsible for delegating blame to one of it's
   * inputs taking into account opacity and similar issues.
   *
   * XXX: What is GeglNode doing in this part of the API?,
   * perhaps we should only point out which pad the data is coming from?
   */
  GeglNode*     (*detect)                    (GeglOperation       *operation,
                                              gint                 x,
                                              gint                 y);

  GeglClRunData *cl_data;

  /* Class method for runtime checks for an operation availability. In
   * particular it allows for operations to be built and installed while
   * depending on runtime dependencies. If is_available() is set and returns
   * %FALSE, then the operation will be set invisible.
   */
  gboolean      (*is_available)              (void);

  gpointer      pad[8];
};

GeglRectangle   gegl_operation_get_invalidated_by_change
                                             (GeglOperation *operation,
                                              const gchar   *input_pad,
                                              const GeglRectangle *roi);
GeglRectangle   gegl_operation_get_bounding_box  (GeglOperation *operation);

/* retrieves the bounding box of an input pad */
GeglRectangle * gegl_operation_source_get_bounding_box
                                             (GeglOperation *operation,
                                              const gchar   *pad_name);


GeglRectangle   gegl_operation_get_cached_region
                                             (GeglOperation *operation,
                                              const GeglRectangle *roi);

GeglRectangle   gegl_operation_get_required_for_output
                                             (GeglOperation *operation,
                                              const gchar   *input_pad,
                                              const GeglRectangle *roi);

GeglNode       *gegl_operation_detect        (GeglOperation *operation,
                                              gint           x,
                                              gint           y);


/* virtual method invokers that change behavior based on the roi being computed,
 * needs a context_id being based that is used for storing context data.
 */

void            gegl_operation_attach        (GeglOperation *operation,
                                              GeglNode      *node);
void            gegl_operation_prepare       (GeglOperation *operation);
gboolean        gegl_operation_process       (GeglOperation *operation,
                                              GeglOperationContext *context,
                                              const gchar          *output_pad,
                                              const GeglRectangle  *roi,
                                              gint                  level);

/* create a pad for a specified property for this operation, this method is
 * to be called from the attach method of operations, most operations do not
 * have to care about this since a super class like filter, sink, source or
 * composer already does so.
 */
void            gegl_operation_create_pad    (GeglOperation *operation,
                                              GParamSpec    *param_spec);

/* specify the bablformat for a pad on this operation (XXX: document when
 * this is legal, at the moment, only used internally in some ops,. but might
 * turn into a global mechanism) */
void            gegl_operation_set_format    (GeglOperation *operation,
                                              const gchar   *pad_name,
                                              const Babl    *format);


const Babl *    gegl_operation_get_format    (GeglOperation *operation,
                                              const gchar   *pad_name);

const gchar *   gegl_operation_get_name      (GeglOperation *operation);


/* checks the incoming Babl format on a given pad, can be used in the prepare
 * stage to make format dependent decisions
 */
const Babl  * gegl_operation_get_source_format (GeglOperation *operation,
                                                const gchar   *padname);

/* retrieves the node providing data to a named input pad */
GeglNode    * gegl_operation_get_source_node   (GeglOperation *operation,
                                                const gchar   *pad_name);

/* API to change  */
void          gegl_operation_class_set_key     (GeglOperationClass *klass,
                                                const gchar *key_name,
                                                const gchar *key_value);

const gchar * gegl_operation_class_get_key     (GeglOperationClass *operation_class,
                                                const gchar        *key_name);

void          gegl_operation_class_set_keys    (GeglOperationClass *klass,
                                                const gchar        *key_name,
                                                ...);


void          gegl_operation_set_key           (const gchar *operation_type,
                                                const gchar *key_name,
                                                const gchar *key_value);


gboolean      gegl_operation_use_opencl         (const GeglOperation *operation);

gboolean      gegl_operation_use_threading         (GeglOperation       *operation,
                                                    const GeglRectangle *roi);
gdouble       gegl_operation_get_pixels_per_thread (GeglOperation       *operation);

/* Invalidate a specific rectangle, indicating the any computation depending
 * on this roi is now invalid.
 *
 * @roi : the region to blank or NULL for the nodes current have_rect
 * @clear_cache: whether any present caches should be zeroed out
 */
void     gegl_operation_invalidate       (GeglOperation       *operation,
                                          const GeglRectangle *roi,
                                          gboolean             clear_cache);

gboolean gegl_operation_cl_set_kernel_args (GeglOperation *operation,
                                            cl_kernel      kernel,
                                            gint          *p,
                                            cl_int        *err);

/* internal utility functions used by gegl, these should not be used
 * externally */
gboolean gegl_can_do_inplace_processing      (GeglOperation       *operation,
                                              GeglBuffer          *input,
                                              const GeglRectangle *result);

/**
 * gegl_object_set_has_forked: (skip)
 * @object: Object to mark
 *
 * Mark an object as "forked", indicating that it should not be modified
 * in place by gegl operations. This should only be used inside of the
 * process method of a GeglOperation subclass.
 */
void     gegl_object_set_has_forked       (GObject *object);

/**
 * gegl_object_get_has_forked: (skip)
 * @object: Object to check
 *
 * Returns TRUE if the object has been marked as "forked".
 */
gboolean  gegl_object_get_has_forked      (GObject *object);

/**
 * gegl_temp_buffer:
 *
 * Returns a singleton scratch buffer for use with multi-threaded processing
 * dispatch.
 */
guchar    *gegl_temp_buffer (int no, int min_size);

void       gegl_operation_progress (GeglOperation *operation, gdouble progress, gchar *message);

const Babl *gegl_operation_get_source_space (GeglOperation *operation, const char *in_pad);


G_END_DECLS

/***
 */

#endif /* __GEGL_OPERATION_H__ */