mypaint-surface.h - libmypaint (HEAD)

Tree @HEAD (Download .tar.gz)

mypaint-surface.h @HEAD — raw · history · blame

#ifndef MYPAINTSURFACE_H
#define MYPAINTSURFACE_H

/* libmypaint - The MyPaint Brush Library
 * Copyright (C) 2008 Martin Renold <martinxyz@gmx.ch>
 * Copyright (C) 2012 Jon Nordby <jononor@gmail.com>
 *
 * Permission to use, copy, modify, and/or distribute this software for any
 * purpose with or without fee is hereby granted, provided that the above
 * copyright notice and this permission notice appear in all copies.
 *
 * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
 * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
 * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
 * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
 * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
 * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 */

#include "mypaint-config.h"
#include "mypaint-rectangle.h"

G_BEGIN_DECLS

typedef struct MyPaintSurface MyPaintSurface;

/*!
 * Function used to retrieve the average color/alpha from a region of a surface.
 *
 * This kind of function calculates the average color/alpha from the pixels
 * of the given surface, selected and weighted respectively by the area
 * and opacity of a uniform dab with a given center and radius.
 *
 * @param self The surface to fetch the pixels from
 * @param x, y The center of the dab that determine which pixels
 * to include, and their respective impact on the result.
 * @param radius The radius of the dab.
 * @param[out] color_r, color_g, color_b, color_a
 * The destination of the resulting colors, range: [0.0, 1.0]
 */
typedef void (*MyPaintSurfaceGetColorFunction) (
  MyPaintSurface *self,
  float x, float y,
  float radius,
  float * color_r, float * color_g, float * color_b, float * color_a
  );

/*!
 * Function used to draw a dab with the given properties on the surface.
 *
 * The function drawing the dab is one of the core parts of any surface
 * implementation. These functions will usually not be invoked directly
 * by library users, but indirectly as part of the ::mypaint_brush_stroke_to
 * call, where the interpolated parameters for each dab are calculated.
 *
 * @param self The surface on which the dab will be drawn
 * @param x, y The center of the dab
 * @param radius The radius of the dab
 * @param color_r, color_g, color_b, opaque color/opacity of the dab
 * @param hardness Determines how opacity is retained for
 * pixels further from the dab center.
 * @param alpha_eraser Hell if I know
 * @param aspect_ratio The width/height ratio of the dab.
 * @param angle The angle of the dab (applied after __aspect_ratio__).
 * @param lock_alpha The extent to which the alpha values of affected pixels
 * on the surface are retained, regardless of other dab parameters.
 * @param colorize: The extent to which the dab will __only__ affect the hue of
 * existing pixels on the surface.
 *
 * @memberof MyPaintSurface
 */
typedef int (*MyPaintSurfaceDrawDabFunction) (
  MyPaintSurface *self,
  float x, float y,
  float radius,
  float color_r, float color_g, float color_b,
  float opaque, float hardness,
  float alpha_eraser,
  float aspect_ratio, float angle,
  float lock_alpha,
  float colorize
  );

/*!
 * Destructor for surface implementations.
 * @param self The surface to free/destroy
 *
 * @memberof MyPaintSurface
 */
typedef void (*MyPaintSurfaceDestroyFunction) (MyPaintSurface *self);

/*!
 * Function for rendering a png file from a surface.
 * @param self The surface to render from
 * @param path The destination of the png file
 * @param x, y The top left corner of the area to export
 * @param width, height The dimensions of the area & of the resulting png
 *
 * @memberof MyPaintSurface
 */
typedef void (*MyPaintSurfaceSavePngFunction) (MyPaintSurface *self, const char *path, int x, int y, int width, int height);

/*!
 * Prepare the surface for an atomic set of stroke operations.
 *
 * Each call to functions of this type should be matched by a call to a
 * ::MyPaintSurfaceEndAtomicFunction with the same surface.
 *
 * @memberof MyPaintSurface
 */
typedef void (*MyPaintSurfaceBeginAtomicFunction) (MyPaintSurface *self);

/*!
 * Finalize an atomic set of stroke operations, setting an invalidation rectangle.
 *
 * Each call to functions of this type should be matched by a call to a
 * ::MyPaintSurfaceBeginAtomicFunction with the same surface.
 *
 * @memberof MyPaintSurface
 */
typedef void (*MyPaintSurfaceEndAtomicFunction) (MyPaintSurface *self, MyPaintRectangle *roi);

/*!
  * Abstract surface type for the MyPaint brush engine. The surface interface
  * lets the brush engine specify dabs to render, and get color data for use
  * in interpolations.
  *
  * @sa MyPaintSurface2
  */
struct MyPaintSurface {
    /*! Function for drawing a dab on the surface.
     *
     * See ::MyPaintSurfaceDrawDabFunction for details.
     */
    MyPaintSurfaceDrawDabFunction draw_dab;
    /*!
     * Function for retrieving color data from the surface.
     *
     * See ::MyPaintSurfaceGetColorFunction for details.
     */
    MyPaintSurfaceGetColorFunction get_color;
    /*!
     * Prepare the surface for a set of atomic stroke/dab operations.
     *
     * See ::MyPaintSurfaceBeginAtomicFunction for details.
     */
    MyPaintSurfaceBeginAtomicFunction begin_atomic;
    /*!
     * Finalize the operations run after a call to #begin_atomic.
     *
     * See ::MyPaintSurfaceEndAtomicFunction for details.
     */
    MyPaintSurfaceEndAtomicFunction end_atomic;
    /*!
    * Destroy the surface (free up all allocated resources).
    */
    MyPaintSurfaceDestroyFunction destroy;
    /*! Save a region of the surface to a png file.
     *
     * See MyPaintSurfaceSavePngFunction for details
     */
    MyPaintSurfaceSavePngFunction save_png;
    /*! Reference count - number of references to the struct
     *
     * This is only useful when used in a context with automatic
     * memory management and can be ignored if construction/destruction
     * is handled manually.
     */
    int refcount;
};

/*!
 * Invoke MyPaintSurface::draw_dab
 *
 * @memberof MyPaintSurface
 * @sa MyPaintSurfaceDrawDabFunction
 */
int mypaint_surface_draw_dab(
    MyPaintSurface* self, float x, float y, float radius, float color_r, float color_g, float color_b, float opaque,
    float hardness, float alpha_eraser, float aspect_ratio, float angle, float lock_alpha, float colorize);

/*!
 * Invoke MyPaintSurface::get_color
 *
 * @memberof MyPaintSurface
 * @sa MyPaintSurfaceGetColorFunction
 */
void mypaint_surface_get_color(
    MyPaintSurface* self, float x, float y, float radius, float* color_r, float* color_g, float* color_b,
    float* color_a);

/*!
 * Invoke MyPaintSurface::get_color and return the alpha component
 *
 * @memberof MyPaintSurface
 * @sa MyPaintSurfaceGetColorFunction
 */
float mypaint_surface_get_alpha(MyPaintSurface* self, float x, float y, float radius);

/*!
 * Invoke MyPaintSurface::save_png
 *
 * @memberof MyPaintSurface
 * @sa MyPaintSurfaceSavePngFunction
 */
void
mypaint_surface_save_png(MyPaintSurface *self, const char *path, int x, int y, int width, int height);


/*!
 * Invoke MyPaintSurface::begin_atomic
 *
 * @memberof MyPaintSurface
 * @sa MyPaintSurfaceBeginAtomicFunction
 */
void mypaint_surface_begin_atomic(MyPaintSurface *self);

/*!
 * Invoke MyPaintSurface::begin_atomic
 *
 * @memberof MyPaintSurface
 * @sa MyPaintSurfaceBeginAtomicFunction
 */
void mypaint_surface_end_atomic(MyPaintSurface *self, MyPaintRectangle *roi);

/*!
 * Set #refcount to 1
 *
 * @memberof MyPaintSurface
 */
void mypaint_surface_init(MyPaintSurface *self);

/*!
 * Increase #refcount by 1
 *
 * @memberof MyPaintSurface
 */

void mypaint_surface_ref(MyPaintSurface *self);

/*!
 * Decrease #refcount by 1 and call #destroy if it reaches 0
 *
 * @memberof MyPaintSurface
 */
void mypaint_surface_unref(MyPaintSurface *self);


/* Extended interface */

typedef struct MyPaintSurface2 MyPaintSurface2;

/*!
 * Like #MyPaintSurfaceDrawDabFunction, but supporting posterization and spectral mixing
 *
 * @param posterize Posterization factor
 * @param posterize_num Number of posterization levels
 * @param paint Spectral mixing factor
 *
 * @sa MyPaintSurfaceDrawDabFunction
 * @memberof MyPaintSurface2
 */
typedef int (*MyPaintSurfaceDrawDabFunction2) (
  MyPaintSurface2 *self,
  float x, float y,
  float radius,
  float color_r, float color_g, float color_b,
  float opaque, float hardness,
  float alpha_eraser,
  float aspect_ratio, float angle,
  float lock_alpha,
  float colorize,
  float posterize,
  float posterize_num,
  float paint);


/*!
 * Like #MyPaintSurfaceGetColorFunction, but for spectral colors.
 *
 * @param paint Spectral mixing factor.
 * To what extent spectral weighting will be used in place of straight averaging.
 * Input value range: [0.0, 1.0]
 *
 * @sa MyPaintSurfaceGetColorFunction
 * @memberof MyPaintSurface2
 */
typedef void (*MyPaintSurfaceGetColorFunction2) (
  MyPaintSurface2 *self,
  float x, float y,
  float radius,
  float * color_r, float * color_g, float * color_b, float * color_a,
  float paint
  );

/*!
 * Like #MyPaintSurfaceEndAtomicFunction, but with support for multiple invalidation rectangles.
 *
 * @sa MyPaintSurfaceEndAtomicFunction
 * @memberof MyPaintSurface2
 */
typedef void (*MyPaintSurfaceEndAtomicFunction2) (MyPaintSurface2 *self, MyPaintRectangles *roi);

/*!
 * Extends MyPaintSurface with support for spectral ops and multiple bounding boxes.
 *
 * This extends the regular MyPaintSurface with three new
 * functions that support the use of spectral blending,
 * for drawing dabs and getting color, and additionally
 * supports using multiple invalidation rectangles when
 * finalizing drawing operations.
 *
 * The interface functions for MyPaintSurface can be called
 * with instances of MyPaintSurface2 via the use of
 * mypaint_surface2_to_surface (or just casting). Concrete
 * implementations of MypaintSurface2 should support this.
 *
 * @sa MyPaintSurface
 */
struct MyPaintSurface2 {
    /*! Parent interface */
    MyPaintSurface parent;
    /*! See #MyPaintSurfaceDrawDabFunction2 */
    MyPaintSurfaceDrawDabFunction2 draw_dab_pigment;
    /*! See #MyPaintSurfaceGetColorFunction2 */
    MyPaintSurfaceGetColorFunction2 get_color_pigment;
    /*! See #MyPaintSurfaceEndAtomicFunction2 */
    MyPaintSurfaceEndAtomicFunction2 end_atomic_multi;
};

/*!
 * Safely access the parent MyPaintSurface interface
 *
 * @memberof MyPaintSurface2
 */
MyPaintSurface* mypaint_surface2_to_surface(MyPaintSurface2 *self);

/*!
 * Call the surface's #get_color_pigment function.
 *
 * See #MyPaintSurfaceGetColorFunction2 for details.
 *
 * @memberof MyPaintSurface2
 */
void mypaint_surface2_get_color(
    MyPaintSurface2* self, float x, float y, float radius,float* color_r, float* color_g, float* color_b,
    float* color_a, float paint);

/*!
 * Call the surface's #end_atomic_multi function.
 *
 * See #MyPaintSurfaceEndAtomicFunction2 for details.
 *
 * @memberof MyPaintSurface2
 */
void mypaint_surface2_end_atomic(MyPaintSurface2 *self, MyPaintRectangles *roi);

/*!
 * Call the surface's #draw_dab_pigment function.
 *
 * See #MyPaintSurfaceDrawDabFunction2 for details.
 *
 * @memberof MyPaintSurface2
 */
int mypaint_surface2_draw_dab(
    MyPaintSurface2* self, float x, float y, float radius, float color_r, float color_g, float color_b, float opaque,
    float hardness, float alpha_eraser, float aspect_ratio, float angle, float lock_alpha, float colorize,
    float posterize, float posterize_num, float paint);

G_END_DECLS

#endif // MYPAINTSURFACE_H