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__ */