test/awtk
1
0
Fork 0
mirror of https://gitee.com/zlgopen/awtk.git synced 2024-12-02 12:08:16 +08:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity
84051f5a36
awtk/3rd/picasso/include/picasso.h
xianjimli 01b9490a8f update picasso
2018-04-26 11:31:20 +08:00

3512 lines
119 KiB
C
Raw Blame History

/**
* \file picasso.h
* \author Zhang Ji Peng <onecoolx@gmail.com>
* \date 2014/6/16
*
* This file includes all interfaces of Picasso
*
\verbatim
Copyright (C) 2008 ~ 2016 Zhang Ji Peng
All rights reserved.
Picasso is a vector graphic library.
\endverbatim
*/
#ifndef _PICASSO_H_
#define _PICASSO_H_
#ifdef DLL_EXPORT
#if defined(WIN32) || defined(WINCE)
#ifdef EXPORT
#define PICAPI
#define PEXPORT __declspec(dllexport)
#else
#define PICAPI
#define PEXPORT __declspec(dllimport)
#endif
#else
#define PICAPI
#if (defined(__GNUC__) && ((__GNUC__ >= 4) || (__GNUC__ == 3 && __GNUC_MINOR__ >= 3))) || (defined(__clang__))
#define PEXPORT __attribute__((visibility("default")))
#else
#define PEXPORT
#endif
#endif
#else
#define PICAPI
#define PEXPORT
#endif
#include "pconfig.h"
#include <stdint.h>
#ifdef __cplusplus
extern "C" {
#endif /* __cplusplus */
/**
* \defgroup data Data Types
* @{
*/
/**
* \typedef ps_bool
* \brief boolean type
* \sa ps_uchar16, ps_schar16, ps_byte
*/
typedef int ps_bool;
/**
* \def True
* \brief define true value
* \sa False
*/
#define True 1
/**
* \def False
* \brief define false value
* \sa True
*/
#define False 0
/**
* \typedef ps_uchar16
* \brief 16 bit unsigned unicode character
* \sa ps_bool, ps_schar16, ps_byte
*/
typedef uint16_t ps_uchar16;
/**
* \typedef ps_schar16
* \brief 16 bit signed unicode character
* \sa ps_bool, ps_uchar16, ps_byte
*/
typedef int16_t ps_schar16;
/**
* \typedef ps_byte
* \brief byte data type
* \sa ps_bool, ps_uchar16, ps_schar16
*/
typedef uint8_t ps_byte;
/** @} end of data types*/
/**
* \defgroup objects Graphic Object Types
* @{
*/
/**
* \typedef ps_context
* \brief An opaque type represents a Picasso drawing environment.
* \sa ps_canvas
*/
typedef struct _ps_context ps_context;
/**
* \typedef ps_canvas
* \brief An opaque type represents a pixel buffer.
* \sa ps_context, ps_image
*/
typedef struct _ps_canvas ps_canvas;
/**
* \typedef ps_image
* \brief An opaque type represents an image.
* \sa ps_canvas, ps_pattern
*/
typedef struct _ps_image ps_image;
/**
* \typedef ps_pattern
* \brief An opaque type represents a pattern.
* \sa ps_canvas, ps_image
*/
typedef struct _ps_pattern ps_pattern;
/**
* \typedef ps_gradient
* \brief An opaque type represents a gradient.
* \sa ps_path, ps_matrix
*/
typedef struct _ps_gradient ps_gradient;
/**
* \typedef ps_matrix
* \brief An opaque type represents a transform matrix.
* \sa ps_path, ps_context
*/
typedef struct _ps_matrix ps_matrix;
/**
* \typedef ps_path
* \brief An opaque type represents a graphic path.
* \sa ps_matrix, ps_context
*/
typedef struct _ps_path ps_path;
/**
* \typedef ps_mask
* \brief An opaque type represents an alpha mask.
* \sa ps_path, ps_image, ps_canvas
*/
typedef struct _ps_mask ps_mask;
/**
* \typedef ps_font
* \brief An opaque type represents a font.
* \sa ps_context
*/
typedef struct _ps_font ps_font;
/**
* \brief A character glyph of a font.
*/
typedef struct _ps_glyph {
/** private glyph data. */
void* glyph;
}ps_glyph;
/**
* \brief A structure that contains width and height values.
*/
typedef struct _ps_size {
/** width value. */
float w;
/** height value. */
float h;
}ps_size;
/**
* \brief A structure that contains location and dimensions of a rectangle.
*/
typedef struct _ps_rect {
/** locate left of the rectangle. */
float x;
/** locate top of the rectangle. */
float y;
/** the width of the rectangle. */
float w;
/** the height of the rectangle. */
float h;
}ps_rect;
/**
* \brief A structure that contains a point in a two-dimensional coordinate system.
*/
typedef struct _ps_point {
/** the x coordinate of the point. */
float x;
/** the y coordinate of the point. */
float y;
}ps_point;
/**
* \brief A structure that contains rgba values for a color.
*/
typedef struct _ps_color {
/** the red component for a color (0 ~ 1). */
float r;
/** the green component for a color (0 ~ 1). */
float g;
/** the blue component for a color (0 ~ 1). */
float b;
/** the alpha component for a color (0 ~ 1). */
float a;
}ps_color;
/** @} end of graphic object types*/
/**
* \defgroup common Common Functions
* @{
*/
/**
* \fn int ps_version(void)
* \brief Return current version of picasso.
* \sa ps_last_status
*/
PEXPORT int PICAPI ps_version(void);
/**
* \fn ps_bool ps_initialize(void)
* \brief Initialize the picasso drawing environment.
*
* It must be the first to be call.
*
* \return True if is initialized, otherwise False.
*
* \sa ps_shutdown
*/
PEXPORT ps_bool PICAPI ps_initialize(void);
/**
* \fn void ps_shutdown(void)
* \brief Shutdown the picasso drawing environment.
*
* It must be call in the end.
*
* \sa ps_initialize
*/
PEXPORT void PICAPI ps_shutdown(void);
/**
* \brief Status code return by call ps_last_status function.
*/
typedef enum _ps_status {
/**
* The successful status no errors.
*/
STATUS_SUCCEED,
/**
* Out of memory.
*/
STATUS_OUT_OF_MEMORY,
/**
* Invalid argument input.
*/
STATUS_INVALID_ARGUMENT,
/**
* Not support this feature.
*/
STATUS_NOT_SUPPORT,
/**
* Device is not ready.
*/
STATUS_DEVICE_ERROR,
/**
* Mismatching error.
*/
STATUS_MISMATCHING_FORMAT,
/**
* Unknown error.
*/
STATUS_UNKNOWN_ERROR,
}ps_status;
/**
* \fn ps_status ps_last_status(void)
* \brief Return the last status code of picasso.
* \sa ps_version
*/
PEXPORT ps_status PICAPI ps_last_status(void);
/** @} end of common functions*/
/**
* \defgroup graphic Graphic Functions
* @{
*/
/**
* \defgroup context Context
* @{
*/
/**
* \fn ps_context* ps_context_create(ps_canvas* canvas, ps_context* shared_context)
* \brief Create a new graphic context for a canvas.
*
* \param canvas Pointer to an existing canvas object.
* \param shared_context Resources shared context, NULL mean resources not shared.
*
* \return If the function succeeds, the return value is the pointer to a new context object.
* If the function fails, the return value is NULL.
*
* \note To get extended error information, call \a ps_last_status.
*
* \sa ps_context_set_canvas, ps_context_get_canvas, ps_context_ref, ps_context_unref
*/
PEXPORT ps_context* PICAPI ps_context_create(ps_canvas* canvas, ps_context* shared_context);
/**
* \fn ps_context* ps_context_ref(ps_context* ctx)
* \brief Increases the reference count of the context by 1.
*
* \param ctx Pointer to an existing context object.
*
* \return If the function succeeds, the return value is the pointer to the context object.
* If the function fails, the return value is NULL.
*
* \note To get extended error information, call \a ps_last_status.
*
* \sa ps_context_set_canvas, ps_context_get_canvas, ps_context_create, ps_context_unref
*/
PEXPORT ps_context* PICAPI ps_context_ref(ps_context* ctx);
/**
* \fn void ps_context_unref(ps_context* ctx)
* \brief Decrements the reference count for the context object.
* If the reference count on the context falls to 0, the context is freed.
*
* \param ctx Pointer to an existing context object.
*
* \sa ps_context_set_canvas, ps_context_get_canvas, ps_context_create, ps_context_ref
*/
PEXPORT void PICAPI ps_context_unref(ps_context* ctx);
/**
* \fn ps_canvas* ps_context_set_canvas(ps_context* ctx, ps_canvas* canvas)
* \brief Set a new canvas into a context, and return the old one.
*
* \param ctx Pointer to an existing context object.
* \param canvas Pointer to an existing canvas object to be set.
*
* \return If the function succeeds, the return value is a pointer to the canvas being replaced.
* If the function fails, the return value is NULL.
*
* \note To get extended error information, call \a ps_last_status.
*
* \sa ps_context_create, ps_context_ref, ps_context_unref, ps_context_get_canvas
*/
PEXPORT ps_canvas* PICAPI ps_context_set_canvas(ps_context* ctx, ps_canvas* canvas);
/**
* \fn ps_canvas* ps_context_get_canvas(ps_context* ctx)
* \brief Get the canvas from the context.
*
* \param ctx Pointer to an existing context object.
*
* \return If the function succeeds, the return value is a pointer to the canvas.
* If the function fails, the return value is NULL.
*
* \note To get extended error information, call \a ps_last_status.
*
* \sa ps_context_create, ps_context_ref, ps_context_unref, ps_context_set_canvas
*/
PEXPORT ps_canvas* PICAPI ps_context_get_canvas(ps_context* ctx);
/** @} end of context functions*/
/**
* \defgroup canvas Canvas
* @{
*/
/**
* \brief Pixel formats of canvas or image.
*/
typedef enum _ps_color_format {
/**
* 32bpp, 8bpc, RGBA color space.
*/
COLOR_FORMAT_RGBA,
/**
* 32bpp, 8bpc, ARGB color space.
*/
COLOR_FORMAT_ARGB,
/**
* 32bpp, 8bpc, ABGR color space.
*/
COLOR_FORMAT_ABGR,
/**
* 32bpp, 8bpc, BGRA color space.
*/
COLOR_FORMAT_BGRA,
/**
* 24bpp, 8bpc, RGB color space.
*/
COLOR_FORMAT_RGB,
/**
* 24bpp, 8bpc, BGR color space.
*/
COLOR_FORMAT_BGR,
/**
* 16bpp, 5/6bpc, RGB color space.
*/
COLOR_FORMAT_RGB565,
/**
* 16bpp, 5bpc, RGB color space.
*/
COLOR_FORMAT_RGB555,
/**
* Unsupported color space.
*/
COLOR_FORMAT_UNKNOWN,
}ps_color_format;
/**
* \fn ps_canvas* ps_canvas_create(ps_color_format fmt, int width, int height)
* \brief Create a new canvas using the given parameters.
*
* \param fmt The Pixel format to use for the canvas.
* \param width The width, in pixels, of the required canvas.
* \param height The height, in pixels, of the required canvas.
*
* \return If the function succeeds, the return value is the pointer to a new canvas object.
* If the function fails, the return value is NULL.
*
* \note To get extended error information, call \a ps_last_status.
*
* \sa ps_canvas_create_with_data, ps_canvas_create_compatible, ps_canvas_create_from_canvas,
* ps_canvas_create_from_image, ps_canvas_ref, ps_canvas_unref
*/
PEXPORT ps_canvas* PICAPI ps_canvas_create(ps_color_format fmt, int width, int height);
/**
* \fn ps_canvas* ps_canvas_create_with_data(ps_byte* data, ps_color_format fmt, int width, int height, int pitch)
* \brief Create a new canvas using a given address in memory.
*
* \param data A pointer to the destination in memory where the drawing is to be rendered.
* The size of this memory block should be at least (pitch * height) bytes.
* \param fmt The Pixel format to use for the canvas.
* \param width The width, in pixels, of the required canvas.
* \param height The height, in pixels, of the required canvas.
* \param pitch The number of bytes per row, of the required canvas.
*
* \return If the function succeeds, the return value is the pointer to a new canvas object.
* If the function fails, the return value is NULL.
*
* \note To get extended error information, call \a ps_last_status.
*
* \sa ps_canvas_create, ps_canvas_create_compatible, ps_canvas_create_from_canvas,
* ps_canvas_create_from_image, ps_canvas_ref, ps_canvas_unref, ps_canvas_replace_data
*/
PEXPORT ps_canvas* PICAPI ps_canvas_create_with_data(ps_byte* data, ps_color_format fmt,
int width, int height, int pitch);
/**
* \fn ps_canvas* ps_canvas_create_compatible(const ps_canvas* canvas, int width, int height)
* \brief Create a new canvas to compatible with an existing canvas.
*
* \param canvas A pointer to an existing canvas.
* \param width The width, in pixels, of the required canvas.
* If it is not more than zero, the width will be equal to the width of the reference canvas.
* \param height The height, in pixels, of the required canvas.
* If it is not more than zero, the height will be equal to the height of the reference canvas.
*
* \return If the function succeeds, the return value is the pointer to a new canvas object.
* If the function fails, the return value is NULL.
*
* \note To get extended error information, call \a ps_last_status.
*
* \sa ps_canvas_create, ps_canvas_create_with_data, ps_canvas_create_from_canvas,
* ps_canvas_create_from_image, ps_canvas_ref, ps_canvas_unref
*/
PEXPORT ps_canvas* PICAPI ps_canvas_create_compatible(const ps_canvas* canvas,
int width, int height);
/**
* \fn ps_canvas* ps_canvas_create_from_canvas(ps_canvas* canvas, const ps_rect* rect)
* \brief Create a new canvas using part of an existing canvas in same pixel buffer.
*
* \param canvas A pointer to an existing canvas.
* \param rect The rectangle area of the canvas from the parent canvas.
* If it is NULL, the canvas's width and height will be equal to the parant canvas.
*
* \return If the function succeeds, the return value is the pointer to a new canvas object.
* If the function fails, the return value is NULL.
*
* \note To get extended error information, call \a ps_last_status.
*
* \sa ps_canvas_create, ps_canvas_create_with_data, ps_canvas_create_compatible,
* ps_canvas_create_from_image, ps_canvas_ref, ps_canvas_unref
*/
PEXPORT ps_canvas* PICAPI ps_canvas_create_from_canvas(ps_canvas* canvas, const ps_rect* rect);
/**
* \fn ps_canvas* ps_canvas_create_from_image(ps_image* img, const ps_rect* rect)
* \brief Create a new canvas using part of an existing ps_image object in same pixel buffer.
*
* \param img A pointer to an existing ps_image object.
* \param rect The rectangle area of the canvas from the ps_image.
* If it is NULL, the canvas's width and height will be equal to ps_image object.
*
* \return If the function succeeds, the return value is the pointer to a new canvas object.
* If the function fails, the return value is NULL.
*
* \note To get extended error information, call \a ps_last_status.
*
* \sa ps_canvas_create, ps_canvas_create_with_data, ps_canvas_create_compatible,
* ps_canvas_create_from_canvas, ps_canvas_ref, ps_canvas_unref
*/
PEXPORT ps_canvas* PICAPI ps_canvas_create_from_image(ps_image* img, const ps_rect* rect);
/**
* \fn ps_canvas* PICAPI ps_canvas_replace_data(ps_canvas* canvas, ps_byte* data,
* ps_color_format fmt, int width, int height, int pitch);
* \brief Replace a canvas target rendering buffer address in memory, which is only use for canvas create by
* \a ps_canvas_create_with_data.
*
* \param canvas Pointer to an existing canvas object.
* \param data A pointer to the destination in memory where the drawing is to be rendered.
* The size of this memory block should be at least (pitch * height) bytes.
* \param fmt The Pixel format to use for the canvas.
* \param width The width, in pixels, of the required canvas.
* \param height The height, in pixels, of the required canvas.
* \param pitch The number of bytes per row, of the required canvas.
*
* \return If the function succeeds, the return value is the pointer to a new canvas object.
* If the function fails, the return value is NULL.
*
* \note The data's color format must be equal with target canvas, otherwish will
* be failed and \a STATUS_MISMATCHING_FORMAT will be set.
*
* \sa ps_canvas_create_with_data
*/
PEXPORT ps_canvas* PICAPI ps_canvas_replace_data(ps_canvas* canvas, ps_byte* data,
ps_color_format fmt, int width, int height, int pitch);
/**
* \fn ps_canvas* ps_canvas_ref(ps_canvas* canvas)
* \brief Increases the reference count of the canvas by 1.
*
* \param canvas Pointer to an existing canvas object.
*
* \return If the function succeeds, the return value is the pointer to the canvas object.
* If the function fails, the return value is NULL.
*
* \note To get extended error information, call \a ps_last_status.
*
* \sa ps_canvas_create, ps_canvas_create_with_data, ps_canvas_create_compatible,
* ps_canvas_create_from_canvas, ps_canvas_create_from_image, ps_canvas_unref
*/
PEXPORT ps_canvas* PICAPI ps_canvas_ref(ps_canvas* canvas);
/**
* \fn void ps_canvas_unref(ps_canvas* canvas)
* \brief Decrements the reference count for the canvas object.
* If the reference count on the canvas falls to 0, the canvas is freed.
*
* \param canvas Pointer to an existing canvas object.
*
* \sa ps_canvas_create, ps_canvas_create_with_data, ps_canvas_create_compatible,
* ps_canvas_create_from_canvas, ps_canvas_create_from_image, ps_canvas_ref
*/
PEXPORT void PICAPI ps_canvas_unref(ps_canvas* canvas);
/**
* \fn ps_bool ps_canvas_get_size(const ps_canvas* canvas, ps_size* rsize)
* \brief Return the size of the canvas.
*
* \param canvas Pointer to an existing canvas object.
* \param rsize Pointer to a buffer to receiving the size.
*
* \return True if is success, otherwise False.
*
* \note To get extended error information, call \a ps_last_status.
*
* \sa ps_canvas_get_format
*/
PEXPORT ps_bool PICAPI ps_canvas_get_size(const ps_canvas* canvas, ps_size* rsize);
/**
* \fn ps_color_format ps_canvas_get_format(const ps_canvas* canvas)
* \brief Return the pixel format of the canvas.
*
* \param canvas Pointer to an existing canvas object.
*
* \return If the function succeeds, the return a valid color format.
* If the function fails, the return value is COLOR_FORMAT_UNKNOWN.
*
* \note To get extended error information, call \a ps_last_status.
*
* \sa ps_canvas_get_size
*/
PEXPORT ps_color_format PICAPI ps_canvas_get_format(const ps_canvas* canvas);
/**
* \fn void ps_canvas_set_mask(ps_canvas* canvas, const ps_mask* mask)
* \brief Set a new mask into an existing canvas object.
*
* \param canvas Pointer to an existing canvas object.
* \param mask Pointer to an existing mask object to be set.
*
* \sa ps_canvas_reset_mask
*/
PEXPORT void PICAPI ps_canvas_set_mask(ps_canvas* canvas, const ps_mask* mask);
/**
* \fn void ps_canvas_reset_mask(ps_canvas* canvas)
* \brief Clear the mask from the canvas object.
*
* \param canvas Pointer to an existing canvas object.
*
* \sa ps_canvas_set_mask
*/
PEXPORT void PICAPI ps_canvas_reset_mask(ps_canvas* canvas);
/**
* \fn void ps_canvas_bitblt(ps_canvas* src, const ps_rect* rect,
* ps_canvas* dst, const ps_point* location)
* \brief Copy raster data between two canvas objects.
*
* \param src The pointer to source canvas object.
* \param rect The rectangle area will be copied in source canvas, NULL mean the whole area.
* \param dst The pointer to destination canvas object.
* \param location The location of the start point at destination canvas object.
*
* \note The two canvas's color format must be equal, otherwish will
* be failed and \a STATUS_MISMATCHING_FORMAT will be set.
*
* \sa ps_canvas_get_size, ps_canvas_get_format
*/
PEXPORT void PICAPI ps_canvas_bitblt(ps_canvas* src, const ps_rect* rect,
ps_canvas* dst, const ps_point* location);
/** @} end of canvas functions*/
/**
* \defgroup image Image
* @{
*/
/**
* \fn ps_image* ps_image_create(ps_color_format fmt, int width, int height)
* \brief Create a new image using the given parameters.
*
* \param fmt The Pixel format to use for the image.
* \param width The width, in pixels, of the required image.
* \param height The height, in pixels, of the required image.
*
* \return If the function succeeds, the return value is the pointer to a new image object.
* If the function fails, the return value is NULL.
*
* \note To get extended error information, call \a ps_last_status.
*
* \sa ps_image_create_with_data, ps_image_create_compatible, ps_image_create_from_canvas,
* ps_image_create_from_data, ps_image_create_from_image, ps_image_ref, ps_image_unref
*/
PEXPORT ps_image* PICAPI ps_image_create(ps_color_format fmt, int width, int height);
/**
* \fn ps_image* ps_image_create_with_data(ps_byte* data, ps_color_format fmt, int width, int height, int pitch)
* \brief Create a new image using a given address in memory.
*
* \param data A pointer to the destination in memory where the drawing is to be rendered.
* The size of this memory block should be at least (pitch * height) bytes.
* \param fmt The Pixel format to use for the image.
* \param width The width, in pixels, of the required image.
* \param height The height, in pixels, of the required image.
* \param pitch The number of bytes per row, of the required image.
*
* \return If the function succeeds, the return value is the pointer to a new image object.
* If the function fails, the return value is NULL.
*
* \note To get extended error information, call \a ps_last_status.
*
* \sa ps_image_create, ps_image_create_compatible, ps_image_create_from_canvas,
* ps_image_create_from_data, ps_image_create_from_image, ps_image_ref, ps_image_unref
*/
PEXPORT ps_image* PICAPI ps_image_create_with_data(ps_byte* data, ps_color_format fmt,
int width, int height, int pitch);
/**
* \fn ps_image* ps_image_create_from_data(ps_byte* data, ps_color_format fmt, int width, int height, int pitch)
* \brief Create a new image using a copy of given address in memory.
*
* \param data A pointer to the destination in memory where the drawing is to be rendered.
* The size of this memory block should be at least (pitch * height) bytes.
* \param fmt The Pixel format to use for the image.
* \param width The width, in pixels, of the required image.
* \param height The height, in pixels, of the required image.
* \param pitch The number of bytes per row, of the required image.
*
* \return If the function succeeds, the return value is the pointer to a new image object.
* If the function fails, the return value is NULL.
*
* \note To get extended error information, call \a ps_last_status.
*
* \sa ps_image_create, ps_image_create_compatible, ps_image_create_from_canvas,
* ps_image_create_with_data, ps_image_create_from_image, ps_image_ref, ps_image_unref
*/
PEXPORT ps_image* PICAPI ps_image_create_from_data(ps_byte* data, ps_color_format fmt,
int width, int height, int pitch);
/**
* \fn ps_image* ps_image_create_compatible(const ps_canvas* canvas, int width, int height)
* \brief Create a new image to compatible with an existing canvas.
*
* \param canvas A pointer to an existing canvas.
* \param width The width, in pixels, of the required canvas.
* If it is not more than zero, the width will be equal to the width of the reference canvas.
* \param height The height, in pixels, of the required canvas.
* If it is not more than zero, the height will be equal to the height of the reference canvas.
*
* \return If the function succeeds, the return value is the pointer to a new image object.
* If the function fails, the return value is NULL.
*
* \note To get extended error information, call \a ps_last_status.
*
* \sa ps_image_create, ps_image_create_with_data, ps_image_create_from_canvas,
* ps_image_create_from_image, ps_image_ref, ps_image_unref
*/
PEXPORT ps_image* PICAPI ps_image_create_compatible(const ps_canvas* canvas, int width, int height);
/**
* \fn ps_image* ps_image_create_from_canvas(ps_canvas* canvas, const ps_rect* rect)
* \brief Create a new image using part of an existing canvas in same pixel buffer.
*
* \param canvas A pointer to an existing canvas.
* \param rect The rectangle area of the image from the ps_canvas.
* If it is NULL, the image's width and height will be equal to the parant canvas.
*
* \return If the function succeeds, the return value is the pointer to a new image object.
* If the function fails, the return value is NULL.
*
* \note To get extended error information, call \a ps_last_status.
*
* \sa ps_image_create, ps_image_create_with_data, ps_image_create_compatible,
* ps_image_create_from_data, ps_image_create_from_image, ps_image_ref, ps_image_unref
*/
PEXPORT ps_image* PICAPI ps_image_create_from_canvas(ps_canvas* canvas, const ps_rect* rect);
/**
* \fn ps_image* ps_image_create_from_image(ps_image* img, const ps_rect* rect)
* \brief Create a new image using part of an existing ps_image object in same pixel buffer.
*
* \param img A pointer to an existing ps_image object.
* \param rect The rectangle area of the image from the parent image.
* If it is NULL, the image's width and height will be equal to parent image object.
*
* \return If the function succeeds, the return value is the pointer to a new image object.
* If the function fails, the return value is NULL.
*
* \note To get extended error information, call \a ps_last_status.
*
* \sa ps_image_create, ps_image_create_with_data, ps_image_create_compatible,
* ps_image_create_from_data, ps_image_create_from_canvas, ps_image_ref, ps_image_unref
*/
PEXPORT ps_image* PICAPI ps_image_create_from_image(ps_image* img, const ps_rect* rect);
/**
* \fn ps_image* ps_image_ref(ps_image* img)
* \brief Increases the reference count of the image by 1.
*
* \param img Pointer to an existing image object.
*
* \return If the function succeeds, the return value is the pointer to the image object.
* If the function fails, the return value is NULL.
*
* \note To get extended error information, call \a ps_last_status.
*
* \sa ps_image_create, ps_image_create_with_data, ps_image_create_compatible,
* ps_image_create_from_data, ps_image_create_from_canvas, ps_image_create_from_image, ps_image_unref
*/
PEXPORT ps_image* PICAPI ps_image_ref(ps_image* img);
/**
* \fn void ps_image_unref(ps_image* img)
* \brief Decrements the reference count for the image object.
* If the reference count on the image falls to 0, the image is freed.
*
* \param img Pointer to an existing image object.
*
* \sa ps_image_create, ps_image_create_with_data, ps_image_create_compatible,
* ps_image_create_from_data, ps_image_create_from_canvas, ps_image_create_from_image, ps_image_ref
*/
PEXPORT void PICAPI ps_image_unref(ps_image* img);
/**
* \fn void ps_image_set_allow_transparent(ps_image* img, ps_bool allow)
* \brief Set whether the image allowed be transparent, False is default.
*
* \param img Pointer to an existing image object.
* \param allow Boolean value whether transparent is allowed.
*
* \sa ps_image_get_format, ps_image_get_size
*/
PEXPORT void PICAPI ps_image_set_allow_transparent(ps_image* img, ps_bool allow);
/**
* \fn void ps_image_set_transparent_color(ps_image* img, const ps_color* color)
* \brief Set the transparent color for the image.
*
* \param img Pointer to an existing image object.
* \param color The color for the transparent, NULL for disable.
*
* \sa ps_image_get_format, ps_image_get_size
*/
PEXPORT void PICAPI ps_image_set_transparent_color(ps_image* img, const ps_color* color);
/**
* \fn ps_bool ps_image_get_size(const ps_image* img, ps_size* rsize)
* \brief Return the size of the image.
*
* \param img Pointer to an existing image object.
* \param rsize Pointer to a buffer to receiving the size.
*
* \return True if is success, otherwise False.
*
* \note To get extended error information, call \a ps_last_status.
*
* \sa ps_image_get_format, ps_image_set_allow_transparent
*/
PEXPORT ps_bool PICAPI ps_image_get_size(const ps_image* img, ps_size* rsize);
/**
* \fn ps_color_format ps_image_get_format(const ps_image* img)
* \brief Return the pixel format of the image.
*
* \param img Pointer to an existing image object.
*
* \return If the function succeeds, the return a valid color format.
* If the function fails, the return value is COLOR_FORMAT_UNKNOWN.
*
* \note To get extended error information, call \a ps_last_status.
*
* \sa ps_image_get_size, ps_image_set_allow_transparent
*/
PEXPORT ps_color_format PICAPI ps_image_get_format(const ps_image* img);
/** @} end of image functions*/
/**
* \defgroup pattern Pattern
* @{
*/
/**
* \brief Fill type of pattern.
*/
typedef enum _ps_wrap_type {
/**
* Wrap repeat, the pattern is repeated.
*/
WRAP_TYPE_REPEAT,
/**
* Wrap reflect the pattern is reflected.
*/
WRAP_TYPE_REFLECT,
}ps_wrap_type;
/**
* \fn ps_pattern* ps_pattern_create_image(const ps_image* img, ps_wrap_type x_wrap,
* ps_wrap_type y_wrap, const ps_matrix* transform)
* \brief Create a new pattern with an existing image.
*
* \param img An existing image object which will be a tiled of pattern object.
* \param x_wrap The horizontal wrap type, of the required pattern.
* \param y_wrap The vertical wrap type, of the required pattern.
* \param transform A matrix that represents a transform for every tiled. If no transform needed, pass NULL.
*
* \return If the function succeeds, the return value is the pointer to a new pattern object.
* If the function fails, the return value is NULL.
*
* \note To get extended error information, call \a ps_last_status.
*
* \sa ps_pattern_ref, ps_pattern_unref
*/
PEXPORT ps_pattern* PICAPI ps_pattern_create_image(const ps_image* img, ps_wrap_type x_wrap,
ps_wrap_type y_wrap, const ps_matrix* transform);
/**
* \fn void ps_pattern_transform(ps_pattern* pattern, const ps_matrix* matrix)
* \brief Transform the pattern object.
*
* \param pattern Pointer to an existing pattern object.
* \param matrix Pointer to an existing matrix object.
*
* \sa ps_pattern_create_image, ps_pattern_ref, ps_pattern_unref
*/
PEXPORT void PICAPI ps_pattern_transform(ps_pattern* pattern, const ps_matrix* matrix);
/**
* \fn ps_pattern* ps_pattern_ref(ps_pattern* pattern)
* \brief Increases the reference count of the pattern by 1.
*
* \param pattern Pointer to an existing pattern object.
*
* \return If the function succeeds, the return value is the pointer to the pattern object.
* If the function fails, the return value is NULL.
*
* \note To get extended error information, call \a ps_last_status.
*
* \sa ps_pattern_create_image, ps_pattern_unref
*/
PEXPORT ps_pattern* PICAPI ps_pattern_ref(ps_pattern* pattern);
/**
* \fn void ps_pattern_unref(ps_pattern* pattern)
* \brief Decrements the reference count for the pattern object.
* If the reference count on the pattern falls to 0, the pattern is freed.
*
* \param pattern Pointer to an existing pattern object.
*
* \sa ps_pattern_create_image, ps_pattern_ref
*/
PEXPORT void PICAPI ps_pattern_unref(ps_pattern* pattern);
/** @} end of pattern functions*/
/**
* \defgroup gradient Gradient
* @{
*/
/**
* \brief Fill type of outside the gradient area.
*/
typedef enum _ps_gradient_spread {
/**
* Spread pad, the area is filled with closest stop color.
*/
GRADIENT_SPREAD_PAD,
/**
* Spread repeat, the gradient is repeated outside the area.
*/
GRADIENT_SPREAD_REPEAT,
/**
* Spread reflect, the gradient is reflected outside the area.
*/
GRADIENT_SPREAD_REFLECT,
}ps_gradient_spread;
/**
* \fn ps_gradient* ps_gradient_create_linear(ps_gradient_spread spread,
* const ps_point* start, const ps_point* end)
* \brief Create a new gradient that varies along the line defined by provided starting and ending points.
*
* \param spread The spread type of the gradient.
* \param start The starting point , of the required gradient.
* \param end The ending point, of the required gradient.
*
* \return If the function succeeds, the return value is the pointer to a new gradient object.
* If the function fails, the return value is NULL.
*
* \note To get extended error information, call \a ps_last_status.
*
* \sa ps_gradient_create_radial, ps_gradient_create_conic, ps_gradient_ref, ps_gradient_unref
*/
PEXPORT ps_gradient* PICAPI ps_gradient_create_linear(ps_gradient_spread spread,
const ps_point* start, const ps_point* end);
/**
* \fn ps_gradient* ps_gradient_create_radial(ps_gradient_spread spread,
* const ps_point* start, float sradius, const ps_point* end, float eradius)
* \brief Create a new gradient that varies along the area defined by provided starting and ending circles.
*
* \param spread The spread type of the gradient.
* \param start The center point of the starting circle, of the required gradient.
* \param sradius The radius of the starting circle, of the required gradient.
* \param end The center point of the ending circle, of the required gradient.
* \param eradius The radius of the ending circle, of the required gradient.
*
* \return If the function succeeds, the return value is the pointer to a new gradient object.
* If the function fails, the return value is NULL.
*
* \note To get extended error information, call \a ps_last_status.
*
* \sa ps_gradient_create_linear, ps_gradient_create_conic, ps_gradient_ref, ps_gradient_unref
*/
PEXPORT ps_gradient* PICAPI ps_gradient_create_radial(ps_gradient_spread spread,
const ps_point* start, float sradius, const ps_point* end, float eradius);
/**
* \fn ps_gradient* ps_gradient_create_conic(ps_gradient_spread spread,
* const ps_point* origin, float sangle)
* \brief Create a new gradient that varies along the area defined by provided concentric circles.
*
* \param spread The spread type of the gradient.
* \param origin The center point of conic, of the required gradient.
* \param sangle The angle, int radians, which the first color.
*
* \return If the function succeeds, the return value is the pointer to a new gradient object.
* If the function fails, the return value is NULL.
*
* \note Conic Gradient support reflect and pad mode only, paramter spread repeat will be supposed pad.
* To get extended error information, call \a ps_last_status.
*
* \sa ps_gradient_create_linear, ps_gradient_create_radial, ps_gradient_ref, ps_gradient_unref
*/
PEXPORT ps_gradient* PICAPI ps_gradient_create_conic(ps_gradient_spread spread,
const ps_point* origin, float sangle);
/**
* \fn void ps_gradient_transform(ps_gradient* gradient, const ps_matrix* matrix)
* \brief Transform the gradient object.
*
* \param gradient Pointer to an existing gradient object.
* \param matrix Pointer to an existing matrix object.
*
* \sa ps_gradient_create_linear, ps_gradient_create_radial,
* ps_gradient_create_conic, ps_gradient_ref, ps_gradient_unref
*/
PEXPORT void PICAPI ps_gradient_transform(ps_gradient* gradient, const ps_matrix* matrix);
/**
* \fn ps_gradient* ps_gradient_ref(ps_gradient* gradient)
* \brief Increases the reference count of the gradient by 1.
*
* \param gradient Pointer to an existing gradient object.
*
* \return If the function succeeds, the return value is the pointer to the gradient object.
* If the function fails, the return value is NULL.
*
* \note To get extended error information, call \a ps_last_status.
*
* \sa ps_gradient_create_linear, ps_gradient_create_radial,
* ps_gradient_create_conic, ps_gradient_unref
*/
PEXPORT ps_gradient* PICAPI ps_gradient_ref(ps_gradient* gradient);
/**
* \fn void ps_gradient_unref(ps_gradient* gradient)
* \brief Decrements the reference count for the gradient object.
* If the reference count on the gradient falls to 0, the gradient is freed.
*
* \param gradient Pointer to an existing gradient object.
*
* \sa ps_gradient_create_linear, ps_gradient_create_radial,
* ps_gradient_create_conic, ps_gradient_ref
*/
PEXPORT void PICAPI ps_gradient_unref(ps_gradient* gradient);
/**
* \fn void ps_gradient_add_color_stop(ps_gradient* gradient, float offset, const ps_color* color)
* \brief Add a color stop to a gradient. The offset specifies the location along the gradient's control vector.
*
* \param gradient Pointer to an existing gradient object.
* \param offset An offset position in control vector (range 0 ~ 1).
* \param color Color for the stop.
*
* \sa ps_gradient_clear_color_stops
*/
PEXPORT void PICAPI ps_gradient_add_color_stop(ps_gradient* gradient,
float offset, const ps_color* color);
/**
* \fn void ps_gradient_clear_color_stops(ps_gradient* gradient)
* \brief Clear color stops from gradient's control vector.
*
* \param gradient Pointer to an existing gradient object.
*
* \sa ps_gradient_add_color_stop
*/
PEXPORT void PICAPI ps_gradient_clear_color_stops(ps_gradient* gradient);
/** @} end of gradient functions*/
/**
* \defgroup mask Mask
* @{
*/
/**
* \fn ps_mask* ps_mask_create_with_data(ps_byte* data, int width, int height)
* \brief Create a new mask using a given data block.
*
* \param data A pointer to the mask data block in memory.
* Each byte of data is a aplha value, from transparent to opaque (0 ~ 255).
* The size of this memory block should be at least (width * height) bytes.
* \param width The width, in pixels, of the required mask.
* \param height The height, in pixels, of the required mask.
*
* \return If the function succeeds, the return value is the pointer to a new mask object.
* If the function fails, the return value is NULL.
*
* \note To get extended error information, call \a ps_last_status.
*
* \sa ps_mask_ref, ps_mask_unref, ps_canvas_set_mask, ps_canvas_reset_mask
*/
PEXPORT ps_mask* PICAPI ps_mask_create_with_data(ps_byte* data, int width, int height);
/**
* \fn ps_mask* ps_mask_ref(ps_mask* mask)
* \brief Increases the reference count of the mask by 1.
*
* \param mask Pointer to an existing mask object.
*
* \return If the function succeeds, the return value is the pointer to the mask object.
* If the function fails, the return value is NULL.
*
* \note To get extended error information, call \a ps_last_status.
*
* \sa ps_mask_create_with_data, ps_mask_unref, ps_canvas_set_mask, ps_canvas_reset_mask
*/
PEXPORT ps_mask* PICAPI ps_mask_ref(ps_mask* mask);
/**
* \fn void ps_mask_unref(ps_mask* mask)
* \brief Decrements the reference count for the mask object.
* If the reference count on the mask falls to 0, the mask is freed.
*
* \param mask Pointer to an existing mask object.
*
* \sa ps_mask_create_with_data, ps_mask_ref, ps_canvas_set_mask, ps_canvas_reset_mask
*/
PEXPORT void PICAPI ps_mask_unref(ps_mask* mask);
/**
* \fn void ps_mask_add_color_filter(ps_mask* mask, const ps_color* color)
* \brief Add a color filter to a mask.
*
* \param mask Pointer to an existing mask object.
* \param color A color for be masked. Only the colors specified by filter can be masked.
* If no color is specified, all colors can be masked.
*
* \sa ps_mask_clear_color_filters
*/
PEXPORT void PICAPI ps_mask_add_color_filter(ps_mask* mask, const ps_color* color);
/**
* \fn void ps_mask_clear_color_filters(ps_mask* mask)
* \brief Clear all colors from mask's filter.
*
* \param mask Pointer to an existing mask object.
*
* \sa ps_mask_add_color_filter
*/
PEXPORT void PICAPI ps_mask_clear_color_filters(ps_mask* mask);
/** @} end of mask functions*/
/**
* \defgroup drawing Drawing
* @{
*/
/**
* \defgroup fill Fill
* @{
*/
/**
* \fn void ps_set_source_color(ps_context* ctx, const ps_color* color)
* \brief Set a Color to the context, it is used to fill a graphic object.
*
* \param ctx Pointer to an existing context object.
* \param color The color to be set.
*
* \sa ps_set_source_image, ps_set_source_pattern, ps_set_source_gradient, ps_set_source_canvas
*/
PEXPORT void PICAPI ps_set_source_color(ps_context* ctx, const ps_color* color);
/**
* \fn void ps_set_source_image(ps_context* ctx, const ps_image* image)
* \brief Set a image to the context, it is used to fill a graphic object.
*
* \param ctx Pointer to an existing context object.
* \param image The image to be set.
*
* \sa ps_set_source_color, ps_set_source_pattern, ps_set_source_gradient, ps_set_source_canvas
*/
PEXPORT void PICAPI ps_set_source_image(ps_context* ctx, const ps_image* image);
/**
* \fn void ps_set_source_pattern(ps_context* ctx, const ps_pattern* pattern)
* \brief Set a pattern to the context, it is used to fill a graphic object.
*
* \param ctx Pointer to an existing context object.
* \param pattern The pattern to be set.
*
* \sa ps_set_source_color, ps_set_source_image, ps_set_source_gradient, ps_set_source_canvas
*/
PEXPORT void PICAPI ps_set_source_pattern(ps_context* ctx, const ps_pattern* pattern);
/**
* \fn void ps_set_source_gradient(ps_context* ctx, const ps_gradient* gradient)
* \brief Set a gradient to the context, it is used to fill a graphic object.
*
* \param ctx Pointer to an existing context object.
* \param gradient The gradient to be set.
*
* \sa ps_set_source_color, ps_set_source_image, ps_set_source_pattern, ps_set_source_canvas
*/
PEXPORT void PICAPI ps_set_source_gradient(ps_context* ctx, const ps_gradient* gradient);
/**
* \fn void ps_set_source_canvas(ps_context* ctx, const ps_canvas* canvas)
* \brief Set a canvas to the context, it is used to fill a graphic object.
*
* \param ctx Pointer to an existing context object.
* \param canvas The canvas to be set.
*
* \sa ps_set_source_color, ps_set_source_image, ps_set_source_pattern, ps_set_source_gradient
*/
PEXPORT void PICAPI ps_set_source_canvas(ps_context* ctx, const ps_canvas* canvas);
/** @} end of fill functions*/
/**
* \defgroup stroke Stroke
* @{
*/
/**
* \brief Styles for rendering the endpoint of a stroked line.
*/
typedef enum _ps_line_cap {
/**
* A line with a squared-off end. The line to extend only to the endpoint.(Default)
*/
LINE_CAP_BUTT,
/**
* A line with a rounded end. The line to extend beyond the endpoint.
*/
LINE_CAP_ROUND,
/**
* A line with a squared-off end. The line to extend beyond the endpoint.
*/
LINE_CAP_SQUARE,
}ps_line_cap;
/**
* \fn void ps_set_line_cap(ps_context* ctx, ps_line_cap line_cap)
* \brief Set the style for the endpoint of lines in a graphics context.
*
* \param ctx Pointer to an existing context object.
* \param line_cap The cap style of the lines.
*
* \sa ps_set_line_join, ps_set_line_width, ps_set_miter_limit, ps_set_stroke_color,
* ps_set_line_dash, ps_reset_line_dash, ps_set_line_inner_join
*/
PEXPORT void PICAPI ps_set_line_cap(ps_context* ctx, ps_line_cap line_cap);
/**
* \brief Junction types for stroked lines.
*/
typedef enum _ps_line_join {
/**
* A join with a sharp corner.(Default)
*/
LINE_JOIN_MITER,
/**
* A join with a sharp corner revert.
*/
LINE_JOIN_MITER_REVERT,
/**
* A join with a miter rounded end.
*/
LINE_JOIN_MITER_ROUND,
/**
* A join with a rounded end.
*/
LINE_JOIN_ROUND,
/**
* A join with a squared-off end.
*/
LINE_JOIN_BEVEL,
}ps_line_join;
/**
* \fn void ps_set_line_join(ps_context* ctx, ps_line_join line_join)
* \brief Set the style for the joins of connected lines in a graphics context.
*
* \param ctx Pointer to an existing context object.
* \param line_join The join style of the lines.
*
* \sa ps_set_line_cap, ps_set_line_width, ps_set_miter_limit, ps_set_stroke_color,
* ps_set_line_dash, ps_reset_line_dash, ps_set_line_inner_join
*/
PEXPORT void PICAPI ps_set_line_join(ps_context* ctx, ps_line_join line_join);
/**
* \brief Inner junction types for stroked lines.
*/
typedef enum _ps_line_inner_join {
/**
* A inner join with a sharp corner.(Default)
*/
LINE_INNER_MITER,
/**
* A inner join with a squared-off end.
*/
LINE_INNER_BEVEL,
/**
* A inner join with a jag end.
*/
LINE_INNER_JAG,
/**
* A inner join with a rounded end.
*/
LINE_INNER_ROUND,
}ps_line_inner_join;
/**
* \fn void ps_set_line_inner_join(ps_context* ctx, ps_line_inner_join line_inner_join)
* \brief Set the style for the inner joins of connected lines in a graphics context.
*
* \param ctx Pointer to an existing context object.
* \param line_inner_join The inner join style of the lines.
*
* \sa ps_set_line_cap, ps_set_line_width, ps_set_miter_limit, ps_set_stroke_color,
* ps_set_line_dash, ps_reset_line_dash, ps_set_line_join
*/
PEXPORT void PICAPI ps_set_line_inner_join(ps_context* ctx, ps_line_inner_join line_inner_join);
/**
* \fn float ps_set_line_width(ps_context* ctx, float width)
* \brief Set the line width for a graphics context.
*
* \param ctx Pointer to an existing context object.
* \param width The line width to use, in pixels, must be greater than 0.
*
* \return If the function succeeds, the return value is the old width.
* If the function fails, the return value is 0.
*
* \note To get extended error information, call \a ps_last_status.
*
* \sa ps_set_line_cap, ps_set_line_join, ps_set_miter_limit, ps_set_stroke_color,
* ps_set_line_dash, ps_reset_line_dash, ps_set_line_inner_join
*/
PEXPORT float PICAPI ps_set_line_width(ps_context* ctx, float width);
/**
* \fn float ps_set_miter_limit(ps_context* ctx, float limit)
* \brief Set the miter limit for the joins of connected lines in a graphics context.
*
* \param ctx Pointer to an existing context object.
* \param limit The miter limit to use.
*
* \return If the function succeeds, the return value is the old miter limit.
* If the function fails, the return value is 0.
*
* \note To get extended error information, call \a ps_last_status.
*
* \sa ps_set_line_cap, ps_set_line_join, ps_set_line_width, ps_set_stroke_color,
* ps_set_line_dash, ps_reset_line_dash, ps_set_line_inner_join
*/
PEXPORT float PICAPI ps_set_miter_limit(ps_context* ctx, float limit);
/**
* \fn void ps_set_stroke_color(ps_context* ctx, const ps_color* color)
* \brief Set a color to the context, it is used to stroke a graphic object.
*
* \param ctx Pointer to an existing context object.
* \param color The color to be set.
*
* \sa ps_set_line_cap, ps_set_line_join, ps_set_line_width, ps_set_miter_limit,
* ps_set_line_dash, ps_reset_line_dash, ps_set_line_inner_join, ps_set_stroke_image
* ps_set_stroke_pattern, ps_set_stroke_gradient, ps_set_stroke_canvas
*/
PEXPORT void PICAPI ps_set_stroke_color(ps_context* ctx, const ps_color* color);
/**
* \fn void ps_set_stroke_image(ps_context* ctx, const ps_image* image)
* \brief Set a image to the context, it is used to stroke a graphic object.
*
* \param ctx Pointer to an existing context object.
* \param image The image to be set.
*
* \sa ps_set_line_cap, ps_set_line_join, ps_set_line_width, ps_set_miter_limit,
* ps_set_line_dash, ps_reset_line_dash, ps_set_line_inner_join, ps_set_stroke_color
* ps_set_stroke_pattern, ps_set_stroke_gradient, ps_set_stroke_canvas
*/
PEXPORT void PICAPI ps_set_stroke_image(ps_context* ctx, const ps_image* image);
/**
* \fn void ps_set_stroke_pattern(ps_context* ctx, const ps_pattern* pattern)
* \brief Set a pattern to the context, it is used to stroke a graphic object.
*
* \param ctx Pointer to an existing context object.
* \param pattern The pattern to be set.
*
* \sa ps_set_line_cap, ps_set_line_join, ps_set_line_width, ps_set_miter_limit,
* ps_set_line_dash, ps_reset_line_dash, ps_set_line_inner_join, ps_set_stroke_color
* ps_set_stroke_image, ps_set_stroke_gradient, ps_set_stroke_canvas
*/
PEXPORT void PICAPI ps_set_stroke_pattern(ps_context* ctx, const ps_pattern* pattern);
/**
* \fn void ps_set_stroke_gradient(ps_context* ctx, const ps_gradient* gradient)
* \brief Set a gradient to the context, it is used to stroke a graphic object.
*
* \param ctx Pointer to an existing context object.
* \param gradient The gradient to be set.
*
* \sa ps_set_line_cap, ps_set_line_join, ps_set_line_width, ps_set_miter_limit,
* ps_set_line_dash, ps_reset_line_dash, ps_set_line_inner_join, ps_set_stroke_color
* ps_set_stroke_image, ps_set_stroke_pattern, ps_set_stroke_canvas
*/
PEXPORT void PICAPI ps_set_stroke_gradient(ps_context* ctx, const ps_gradient* gradient);
/**
* \fn void ps_set_stroke_canvas(ps_context* ctx, const ps_canvas* canvas)
* \brief Set a canvas to the context, it is used to stroke a graphic object.
*
* \param ctx Pointer to an existing context object.
* \param canvas The canvas to be set.
*
* \sa ps_set_line_cap, ps_set_line_join, ps_set_line_width, ps_set_miter_limit,
* ps_set_line_dash, ps_reset_line_dash, ps_set_line_inner_join, ps_set_stroke_color
* ps_set_stroke_image, ps_set_stroke_pattern, ps_set_stroke_gradient
*/
PEXPORT void PICAPI ps_set_stroke_canvas(ps_context* ctx, const ps_canvas* canvas);
/**
* \fn void ps_set_line_dash(ps_context* ctx, float start, const float* dashes, unsigned int num_dashes)
* \brief Set the pattern for dashed lines in the context.
*
* \param ctx Pointer to an existing context object.
* \param start A value that specifies how far into the dash pattern the line start.
* \param dashes An array of values that specify the length of the painted segments and
* unpainted segments.
* \param num_dashes The number of elements in the array.
*
* \sa ps_set_line_cap, ps_set_line_join, ps_set_line_width, ps_set_miter_limit,
* ps_set_stroke_color, ps_reset_line_dash, ps_set_line_inner_join
*/
PEXPORT void PICAPI ps_set_line_dash(ps_context* ctx, float start,
const float* dashes, unsigned int num_dashes);
/**
* \fn void ps_reset_line_dash(ps_context* ctx)
* \brief Clear the dashs from the context, and set to solid.
*
* \param ctx Pointer to an existing context object.
*
* \sa ps_set_line_cap, ps_set_line_join, ps_set_line_width, ps_set_miter_limit,
* ps_set_stroke_color, ps_set_line_dash, ps_set_line_inner_join
*/
PEXPORT void PICAPI ps_reset_line_dash(ps_context* ctx);
/** @} end of stroke functions*/
/**
* \defgroup shadow Shadow
* @{
*/
/**
* \fn void ps_set_shadow(ps_context* ctx, float x_offset, float y_offset, float blur)
* \brief Enables shadowing in a context.
*
* \param ctx Pointer to an existing context object.
* \param x_offset Offset on horizontal from origin (0,0).
* \param y_offset Offset on vertical from origin (0,0).
* \param blur Specifying the amount of blur (0 ~ 1).
*
* \sa ps_set_shadow_color, ps_reset_shadow
*/
PEXPORT void PICAPI ps_set_shadow(ps_context* ctx, float x_offset, float y_offset, float blur);
/**
* \fn void ps_set_shadow_color(ps_context* ctx, const ps_color* color)
* \brief Set the color of shadow. Default is a black color with 1/3 alpha.
*
* \param ctx Pointer to an existing context object.
* \param color Specifies the color of the shadow.
*
* \sa ps_set_shadow, ps_reset_shadow
*/
PEXPORT void PICAPI ps_set_shadow_color(ps_context* ctx, const ps_color* color);
/**
* \fn void ps_reset_shadow(ps_context* ctx)
* \brief Disables shadowing in a context.
*
* \param ctx Pointer to an existing context object.
*
* \sa ps_set_shadow_color, ps_set_shadow
*/
PEXPORT void PICAPI ps_reset_shadow(ps_context* ctx);
/** @} end of shadow functions*/
/**
* \defgroup attr Attribute
* @{
*/
/**
* \brief Compositing operations for graphics context.
*/
typedef enum _ps_composite {
/** Clear operation. */
COMPOSITE_CLEAR,
/** Source operation. */
COMPOSITE_SRC,
/** Source over operation. (Default) */
COMPOSITE_SRC_OVER,
/** Source in operation. */
COMPOSITE_SRC_IN,
/** Source out operation. */
COMPOSITE_SRC_OUT,
/** Source atop operation. */
COMPOSITE_SRC_ATOP,
/** Destination operation. */
COMPOSITE_DST,
/** Destination over operation. */
COMPOSITE_DST_OVER,
/** Destination in operation. */
COMPOSITE_DST_IN,
/** Destination out operation. */
COMPOSITE_DST_OUT,
/** Destination atop operation. */
COMPOSITE_DST_ATOP,
/** Xor operation. */
COMPOSITE_XOR,
/** Source darker operation. */
COMPOSITE_DARKEN,
/** Source lighter operation. */
COMPOSITE_LIGHTEN,
/** Overlay operation. */
COMPOSITE_OVERLAY,
/** Screen operation. */
COMPOSITE_SCREEN,
/** Multiply operation. */
COMPOSITE_MULTIPLY,
/** Plus operation. */
COMPOSITE_PLUS,
/** Minus operation. */
COMPOSITE_MINUS,
/** Exclusion operation. */
COMPOSITE_EXCLUSION,
/** Difference operation. */
COMPOSITE_DIFFERENCE,
/** Softlight operation. */
COMPOSITE_SOFTLIGHT,
/** Hardlight operation. */
COMPOSITE_HARDLIGHT,
/** Burn operation. */
COMPOSITE_BURN,
/** Dodge operation. */
COMPOSITE_DODGE,
/** Contrast operation. */
COMPOSITE_CONTRAST,
/** Invert operation. */
COMPOSITE_INVERT,
/** Invert blend operation. */
COMPOSITE_INVERT_BLEND,
/** Hue operation. */
COMPOSITE_HUE,
/** Saturation operation. */
COMPOSITE_SATURATION,
/** Color operation. */
COMPOSITE_COLOR,
/** Luminosity operation. */
COMPOSITE_LUMINOSITY,
/** Error value. */
COMPOSITE_ERROR,
}ps_composite;
/**
* \fn ps_composite ps_set_composite_operator(ps_context* ctx, ps_composite composite)
* \brief Set composites opertaions for graphics context.
*
* \param ctx Pointer to an existing context object.
* \param composite The Composite operation to be set.
*
* \return If the function succeeds, the return value is the old operation.
* If the function fails, the return value is COMPOSITE_ERROR.
*
* \note To get extended error information, call \a ps_last_status.
*
* \sa ps_set_filter, ps_set_fill_rule
*/
PEXPORT ps_composite PICAPI ps_set_composite_operator(ps_context* ctx, ps_composite composite);
/**
* \brief Graphics quality for rendering an image.
*/
typedef enum _ps_filter {
/**
* No interpolation filter.
*/
FILTER_NEAREST,
/**
* Bilinear interpolation filter. (Default)
*/
FILTER_BILINEAR,
/**
* Gaussian interpolation filter.
*/
FILTER_GAUSSIAN,
/**
* Error value.
*/
FILTER_UNKNOWN,
}ps_filter;
/**
* \fn ps_filter ps_set_filter(ps_context* ctx, ps_filter filter)
* \brief Set interpolation filter for graphic context.
*
* \param ctx Pointer to an existing context object.
* \param filter The interpolation filter to be set.
*
* \return If the function succeeds, the return value is the old filter.
* If the function fails, the return value is FILTER_UNKNOWN.
*
* \note To get extended error information, call \a ps_last_status.
*
* \sa ps_set_composite_operator, ps_set_fill_rule
*/
PEXPORT ps_filter PICAPI ps_set_filter(ps_context* ctx, ps_filter filter);
/**
* \brief Fill rules for graphics.
*/
typedef enum _ps_fill_rule {
/**
* Nonzero winding fill rule. (Default)
*/
FILL_RULE_WINDING,
/**
* Even-odd fill rule.
*/
FILL_RULE_EVEN_ODD,
/**
* Error value.
*/
FILL_RULE_ERROR,
}ps_fill_rule;
/**
* \fn ps_fill_rule ps_set_fill_rule(ps_context* ctx, ps_fill_rule rule)
* \brief Set fill rule for graphic context.
*
* \param ctx Pointer to an existing context object.
* \param rule The fill rule to be set.
*
* \return If the function succeeds, the return value is the old rule.
* If the function fails, the return value is FILL_RULE_ERROR.
*
* \note To get extended error information, call \a ps_last_status.
*
* \sa ps_set_composite_operator, ps_set_filter
*/
PEXPORT ps_fill_rule PICAPI ps_set_fill_rule(ps_context* ctx, ps_fill_rule rule);
/**
* \fn float ps_set_alpha(ps_context* ctx, float alpha)
* \brief Set the opacity level for objects drawn in graphic context.
*
* \param ctx Pointer to an existing context object.
* \param alpha A value that specifies the opacity level from transparent to opaque(0 ~ 1).
* Default level is opaque (1).
*
* \return If the function succeeds, the return value is the old level.
* If the function fails, the return value is 0.
*
* \note To get extended error information, call \a ps_last_status.
*
* \sa ps_set_gamma, ps_set_blur, ps_set_antialias
*/
PEXPORT float PICAPI ps_set_alpha(ps_context* ctx, float alpha);
/**
* \fn float ps_set_gamma(ps_context* ctx, float gamma)
* \brief Set the gamma value for the graphic context.
*
* \param ctx Pointer to an existing context object.
* \param gamma A value that specifies the gamma (0 ~ 3).
* Default value is 1.
*
* \return If the function succeeds, the return value is the old one.
* If the function fails, the return value is 0.
*
* \note To get extended error information, call \a ps_last_status.
*
* \sa ps_set_alpha, ps_set_blur, ps_set_antialias
*/
PEXPORT float PICAPI ps_set_gamma(ps_context* ctx, float gamma);
/**
* \fn void ps_set_antialias(ps_context* ctx, ps_bool antialias)
* \brief Set whether the Anti-aliasing should be turn on.
*
* \param ctx Pointer to an existing context object.
* \param antialias Boolean value whether the anti-aliasing is turn on. (True default)
*
* \sa ps_set_alpha, ps_set_blur, ps_set_gamma
*/
PEXPORT void PICAPI ps_set_antialias(ps_context* ctx, ps_bool antialias);
/**
* \fn float ps_set_blur(ps_context* ctx, float blur)
* \brief Set the blur level for the graphic context.
*
* \param ctx Pointer to an existing context object.
* \param blur A value that specifies the blur level (0 ~ 1).
* Default value is none blur (0).
*
* \return If the function succeeds, the return value is the old level.
* If the function fails, the return value is 0.
*
* \note To get extended error information, call \a ps_last_status.
*
* \sa ps_set_alpha, ps_set_gamma, ps_set_antialias
*/
PEXPORT float PICAPI ps_set_blur(ps_context* ctx, float blur);
/** @} end of attr functions*/
/**
* \defgroup paint Paint
* @{
*/
/**
* \fn void ps_stroke(ps_context* ctx)
* \brief Stroke the current path according to the line attributes.
* After called, the current path will be cleared from the context.
*
* \param ctx Pointer to an existing context object.
*
* \sa ps_fill, ps_paint, ps_clear
*/
PEXPORT void PICAPI ps_stroke(ps_context* ctx);
/**
* \fn void ps_fill(ps_context* ctx)
* \brief Fill the current path according to the source attributes.
* After called, the current path will be cleared from the context.
*
* \param ctx Pointer to an existing context object.
*
* \sa ps_stroke, ps_paint, ps_clear
*/
PEXPORT void PICAPI ps_fill(ps_context* ctx);
/**
* \fn void ps_paint(ps_context* ctx)
* \brief Fill and stroke the current path according to the source and line attributes.
* After called, the current path will be cleared from the context.
*
* \param ctx Pointer to an existing context object.
*
* \sa ps_stroke, ps_fill, ps_clear
*/
PEXPORT void PICAPI ps_paint(ps_context* ctx);
/**
* \fn void ps_clear(ps_context* ctx)
* \brief Clear the current context with source color.
*
* \param ctx Pointer to an existing context object.
*
* \sa ps_stroke, ps_fill, ps_paint
*/
PEXPORT void PICAPI ps_clear(ps_context* ctx);
/** @} end of paint functions*/
/**
* \defgroup clip Clip
* @{
*/
/**
* \fn void ps_clip(ps_context* ctx)
* \brief Clipping the current path, using the current fill rule.
* After called, the current path will be cleared from the context.
*
* \param ctx Pointer to an existing context object.
*
* \sa ps_clip_path, ps_clip_rect, ps_clip_rects, ps_reset_clip
*/
PEXPORT void PICAPI ps_clip(ps_context* ctx);
/**
* \fn void ps_clip_path(ps_context* ctx, const ps_path* path, ps_fill_rule rule)
* \brief Clipping specified path, using the given fill rule.
*
* \param ctx Pointer to an existing context object.
* \param path The path which will be clipped.
* \param rule The rule of the path.
*
* \sa ps_clip, ps_clip_rect, ps_clip_rects, ps_reset_clip
*/
PEXPORT void PICAPI ps_clip_path(ps_context* ctx, const ps_path* path, ps_fill_rule rule);
/**
* \fn void ps_clip_rect(ps_context* ctx, const ps_rect* rect)
* \brief Clipping specified rectangle.
*
* \param ctx Pointer to an existing context object.
* \param rect The rectangle which will be clipped.
*
* \sa ps_clip, ps_clip_path, ps_clip_rects, ps_reset_clip, ps_clip_device_rect
*/
PEXPORT void PICAPI ps_clip_rect(ps_context* ctx, const ps_rect* rect);
/**
* \fn void ps_clip_device_rect(ps_context* ctx, const ps_rect* rect)
* \brief The fast way to clipping specified rectangle, the clip rect can not be rotated
* by world matrix. (Deprecated)
*
* \param ctx Pointer to an existing context object.
* \param rect The rectangle which will be clipped.
*
* \note This function is deprecated, will be remove feature.
*
* \sa ps_clip, ps_clip_path, ps_clip_rects, ps_reset_clip, ps_clip_rect
*/
PEXPORT void PICAPI ps_clip_device_rect(ps_context* ctx, const ps_rect* rect);
/**
* \fn void ps_clip_rects(ps_context* ctx, const ps_rect* rects, unsigned int num_rects)
* \brief Clipping specified area defined by an array of rectangles.
*
* \param ctx Pointer to an existing context object.
* \param rects The array of rectangles which will be clipped.
* \param num_rects The number of array entries.
*
* \sa ps_clip, ps_clip_path, ps_clip_rect, ps_reset_clip
*/
PEXPORT void PICAPI ps_clip_rects(ps_context* ctx, const ps_rect* rects, unsigned int num_rects);
/**
* \fn void ps_reset_clip(ps_context* ctx)
* \brief Clear the clipping area from the context.
*
* \param ctx Pointer to an existing context object.
*
* \sa ps_clip, ps_clip_path, ps_clip_rect, ps_clip_rects
*/
PEXPORT void PICAPI ps_reset_clip(ps_context* ctx);
/** @} end of clip functions*/
/**
* \defgroup state State
* @{
*/
/**
* \fn void ps_save(ps_context* ctx)
* \brief Pushes a copy of the current graphics state on to stack for context.
*
* \param ctx Pointer to an existing context object.
* The graphics state saved are:
* - Image filter
* - Font object
* - Gamma value
* - Alpha value
* - Blur value
* - Text stroke color
* - Text fill color
* - Compositing method
* - Transform matrix
* - Line width
* - Line cap
* - Line join
* - Line dash
* - Stroke object
* - Source object
* - Fill color
* - Fill rule
* - Clip region
* - Shadow parameters
*
* \sa ps_restore
*/
PEXPORT void PICAPI ps_save(ps_context* ctx);
/**
* \fn void ps_restore(ps_context* ctx)
* \brief Set the current graphics state to the state most recently saved.
*
* \param ctx Pointer to an existing context object.
*
* \sa ps_save
*/
PEXPORT void PICAPI ps_restore(ps_context* ctx);
/** @} end of state functions*/
/** @} end of drawing functions*/
/**
* \defgroup font Font
* @{
*/
/**
* \brief Charset for a font.
*/
typedef enum _ps_charset {
/**
* Ansi ISO-8859-x charset
*/
CHARSET_ANSI,
/**
* Unicode UCS-2 charset
*/
CHARSET_UNICODE,
}ps_charset;
/**
* \brief Font weight
*/
typedef enum _ps_font_weight {
/**
* Regular weight.
*/
FONT_WEIGHT_REGULAR = 400,
/**
* Medium weight.
*/
FONT_WEIGHT_MEDIUM = 500,
/**
* Bold weight.
*/
FONT_WEIGHT_BOLD = 700,
/**
* Heavy weight.
*/
FONT_WEIGHT_HEAVY = 900,
}ps_font_weight;
/**
* \fn ps_font* ps_font_create(const char* name, ps_charset charset, float size, int weight, ps_bool italic)
* \brief Create a font object using the given parameters.
*
* \param name The font family name.
* \param charset The charset type.
* \param size The font size.
* \param weight The font weight.
* \param italic Whether or not it is italic.
*
* \return If the function succeeds, the return value is the pointer to a new font object.
* If the function fails, the return value is NULL.
*
* \note To get extended error information, call \a ps_last_status.
*
* \sa ps_font_create_copy, ps_font_ref, ps_font_unref
*/
PEXPORT ps_font* PICAPI ps_font_create(const char* name, ps_charset charset,
float size, int weight, ps_bool italic);
/**
* \fn ps_font* ps_font_create_copy(const ps_font* font)
* \brief Create a copy from an existing font object.
*
* \param font Pointer to an existing font object.
*
* \return If the function succeeds, the return value is the pointer to a new font object.
* If the function fails, the return value is NULL.
*
* \note To get extended error information, call \a ps_last_status.
*
* \sa ps_font_create, ps_font_ref, ps_font_unref
*/
PEXPORT ps_font* PICAPI ps_font_create_copy(const ps_font* font);
/**
* \fn ps_font* ps_font_ref(ps_font* font)
* \brief Increases the reference count of the font by 1.
*
* \param font Pointer to an existing font object.
*
* \return If the function succeeds, the return value is the pointer to the font object.
* If the function fails, the return value is NULL.
*
* \note To get extended error information, call \a ps_last_status.
*
* \sa ps_font_create, ps_font_create_copy, ps_font_unref
*/
PEXPORT ps_font* PICAPI ps_font_ref(ps_font* font);
/**
* \fn void ps_font_unref(ps_font* font)
* \brief Decrements the reference count for the font object.
* If the reference count on the font falls to 0, the font is freed.
*
* \param font Pointer to an existing font object.
*
* \sa ps_font_create, ps_font_create_copy, ps_font_ref
*/
PEXPORT void PICAPI ps_font_unref(ps_font* font);
/**
* \fn void ps_font_set_size(ps_font* font, float size)
* \brief Set size for a font object.
*
* \param font Pointer to an existing font object.
* \param size Size for the font.
*
* \sa ps_font_set_weight, ps_font_set_italic, ps_font_set_charset,
* ps_font_set_hint, ps_font_set_flip
*/
PEXPORT void PICAPI ps_font_set_size(ps_font* font, float size);
/**
* \fn void ps_font_set_weight(ps_font* font, int weight)
* \brief Set weight for a font object.
*
* \param font Pointer to an existing font object.
* \param weight Weight for the font.
*
* \sa ps_font_set_size, ps_font_set_italic, ps_font_set_charset,
* ps_font_set_hint, ps_font_set_flip
*/
PEXPORT void PICAPI ps_font_set_weight(ps_font* font, int weight);
/**
* \fn void ps_font_set_italic(ps_font* font, ps_bool italic)
* \brief Set italic for a font object.
*
* \param font Pointer to an existing font object.
* \param italic Whether or not italic for the font. (False default)
*
* \sa ps_font_set_size, ps_font_set_weight, ps_font_set_charset,
* ps_font_set_hint, ps_font_set_flip
*/
PEXPORT void PICAPI ps_font_set_italic(ps_font* font, ps_bool italic);
/**
* \fn void ps_font_set_charset(ps_font* font, ps_charset charset)
* \brief Set charset for a font object.
*
* \param font Pointer to an existing font object.
* \param charset Charset for the font.
*
* \sa ps_font_set_size, ps_font_set_weight, ps_font_set_italic,
* ps_font_set_hint, ps_font_set_flip
*/
PEXPORT void PICAPI ps_font_set_charset(ps_font* font, ps_charset charset);
/**
* \fn void ps_font_set_hint(ps_font* font, ps_bool hint)
* \brief Set hiting for a font object.
*
* \param font Pointer to an existing font object.
* \param hint Whether or not auto hiting for the font. (True default)
*
* \sa ps_font_set_size, ps_font_set_weight, ps_font_set_italic,
* ps_font_set_charset, ps_font_set_flip
*/
PEXPORT void PICAPI ps_font_set_hint(ps_font* font, ps_bool hint);
/**
* \fn void ps_font_set_flip(ps_font* font, ps_bool flip)
* \brief Set flip for a font object.
*
* \param font Pointer to an existing font object.
* \param flip Whether or not flip y for the font. (False default)
*
* \sa ps_font_set_size, ps_font_set_weight, ps_font_set_italic,
* ps_font_set_charset, ps_font_set_hint
*/
PEXPORT void PICAPI ps_font_set_flip(ps_font* font, ps_bool flip);
/**
* \brief A structure that contains font information.
*/
typedef struct _ps_font_info {
/**
* Size, the height of glyph.
*/
float size;
/**
* Ascent, maximum distance above the baseline.
*/
float ascent;
/**
* Descent, maximum distance below the baseline.
*/
float descent;
/**
* Leading, the spaceing between consecutive lines of text.
*/
float leading;
/**
* UnitsEm, the number of glyph space units per em.
*/
unsigned int unitsEM;
}ps_font_info;
/**
* \fn ps_bool ps_get_font_info(ps_context* ctx, ps_font_info* info)
* \brief Return the font information from the graphics context.
*
* \param ctx Pointer to an existing context object.
* \param info Pointer to a structure to receiving the font information.
*
* \return True if is success, otherwise False.
*
* \sa ps_set_font
*/
PEXPORT ps_bool PICAPI ps_get_font_info(ps_context* ctx, ps_font_info* info);
/**
* \fn ps_font* ps_set_font(ps_context* ctx, const ps_font* font)
* \brief Set a new font to graphics context.
*
* \param ctx Pointer to an existing context object.
* \param font The new font to be set.
*
* \return If the function succeeds, the return value is the pointer to old font object.
* If the function fails, the return value is NULL.
*
* \note To get extended error information, call \a ps_last_status.
*
* \sa ps_get_font_info
*/
PEXPORT ps_font* PICAPI ps_set_font(ps_context* ctx, const ps_font* font);
/** @} end of font functions*/
/**
* \defgroup text Text
* @{
*/
/**
* \brief Text rendering type
*/
typedef enum _ps_text_type {
/**
* Smooth rendering.
*/
TEXT_TYPE_SMOOTH,
/**
* Mono rendering.
*/
TEXT_TYPE_MONO,
/**
* OutLine rendering.
*/
TEXT_TYPE_STROKE,
}ps_text_type;
/**
* \fn ps_bool ps_get_text_extent(ps_context* ctx, const void* text, unsigned int length, ps_size* rsize)
* \brief Get extent for text using current font which selected to graphic context.
*
* \param ctx Pointer to an existing context object.
* \param text Text which being tested. It can be latin-1 or unicode encoding.
* \param length Length of the text.
* \param rsize Pointer to a buffer to receiving the size.
*
* \return True if is success, otherwise False.
*
* \note To get extended error information, call \a ps_last_status.
*
* \sa ps_glyph_get_extent
*/
PEXPORT ps_bool PICAPI ps_get_text_extent(ps_context* ctx, const void* text, unsigned int length, ps_size* rsize);
/**
* \fn void ps_set_text_color(ps_context* ctx, const ps_color * color)
* \brief Set the text fill color for the graphic context.
*
* \param ctx Pointer to an existing context object.
* \param color The text fill color.
*
* \sa ps_transform, ps_set_text_matrix, ps_set_text_antialias,
* ps_set_text_stroke_color, ps_set_text_render_type, ps_set_text_kerning
*/
PEXPORT void PICAPI ps_set_text_color(ps_context* ctx, const ps_color * color);
/**
* \fn void ps_set_text_stroke_color(ps_context* ctx, const ps_color * color)
* \brief Set the text stroke color for the graphic context.
*
* \param ctx Pointer to an existing context object.
* \param color The text stroke color.
*
* \sa ps_set_text_color, ps_set_text_matrix, ps_set_text_antialias,
* ps_text_transform, ps_set_text_render_type, ps_set_text_kerning
*/
PEXPORT void PICAPI ps_set_text_stroke_color(ps_context* ctx, const ps_color * color);
/**
* \fn void ps_text_transform(ps_context* ctx, const ps_matrix* matrix)
* \brief Transform text matrix for the graphic context.
* The text matrix is not a part of graphic state -- saving and restoring has no
* effect on the text matrix. The text matrix is an attribute of graphic context.
*
* \param ctx Pointer to an existing context object.
* \param matrix Pointer to an existing matrix object.
*
* \sa ps_set_text_matrix, ps_set_text_antialias, ps_set_text_color,
* ps_set_text_stroke_color, ps_set_text_render_type, ps_set_text_kerning
*/
PEXPORT void PICAPI ps_text_transform(ps_context* ctx, const ps_matrix* matrix);
/**
* \fn void ps_set_text_matrix(ps_context* ctx, const ps_matrix* matrix)
* \brief Set text matrix for the graphic context.
* The text matrix is not a part of graphic state -- saving and restoring has no
* effect on the text matrix. The text matrix is an attribute of graphic context.
*
* \param ctx Pointer to an existing context object.
* \param matrix Pointer to an existing matrix object.
*
* \sa ps_text_transform, ps_set_text_antialias, ps_set_text_color,
* ps_set_text_stroke_color, ps_set_text_render_type, ps_set_text_kerning
*/
PEXPORT void PICAPI ps_set_text_matrix(ps_context* ctx, const ps_matrix* matrix);
/**
* \fn void ps_set_text_render_type(ps_context* ctx, ps_text_type type)
* \brief Set rendering type for text.
*
* \param ctx Pointer to an existing context object.
* \param type Rendering type for the text.
*
* \sa ps_set_text_matrix, ps_set_text_color, ps_set_text_stroke_color,
* ps_set_text_antialias, ps_text_transform, ps_set_text_kerning
*/
PEXPORT void PICAPI ps_set_text_render_type(ps_context* ctx, ps_text_type type);
/**
* \fn void ps_set_text_antialias(ps_context* ctx, ps_bool antialias)
* \brief Set whether the font allowed be anti-aliasing.
*
* \param ctx Pointer to an existing context object.
* \param antialias Boolean value whether anti-aliasing is allowed. (True default)
*
* \sa ps_set_text_matrix, ps_set_text_color, ps_set_text_stroke_color,
* ps_set_text_render_type, ps_text_transform, ps_set_text_kerning
*/
PEXPORT void PICAPI ps_set_text_antialias(ps_context* ctx, ps_bool antialias);
/**
* \fn void ps_set_text_kerning(ps_context* ctx, ps_bool kerning)
* \brief Set whether the font auto kerning is allowed.
*
* \param ctx Pointer to an existing context object.
* \param kerning Boolean value whether auto kerning is allowed. (True default)
*
* \sa ps_set_text_matrix, ps_set_text_color, ps_set_text_stroke_color,
* ps_set_text_render_type, ps_text_transform, ps_set_text_antialias
*/
PEXPORT void PICAPI ps_set_text_kerning(ps_context* ctx, ps_bool kerning);
/**
* \fn void ps_text_out_length(ps_context* ctx, float x, float y, const char* text, unsigned int length)
* \brief Draw single byte characters (latin-1) at location in user space.
*
* \param ctx Pointer to an existing context object.
* \param x The X-coordinate at which to draw the text.
* \param y The Y-coordinate at which to draw the text.
* \param text The text string to be draw.
* \param length The length of the text string.
*
* \sa ps_wide_text_out_length, ps_draw_text
*/
PEXPORT void PICAPI ps_text_out_length(ps_context* ctx, float x, float y,
const char* text, unsigned int length);
/**
* \fn void ps_wide_text_out_length(ps_context* ctx, float x, float y, const ps_uchar16* text, unsigned int length)
* \brief Draw unicode characters (ucs-2) at location in user space.
*
* \param ctx Pointer to an existing context object.
* \param x The X-coordinate at which to draw the text.
* \param y The Y-coordinate at which to draw the text.
* \param text The unicode text string to be draw.
* \param length The length of the text string.
*
* \sa ps_text_out_length, ps_draw_text
*/
PEXPORT void PICAPI ps_wide_text_out_length(ps_context* ctx, float x, float y,
const ps_uchar16* text, unsigned int length);
/**
* \brief Draw mode for rending text.
*/
typedef enum _ps_draw_text_type {
/**
* Perform a fill operation on the text.
*/
DRAW_TEXT_FILL,
/**
* Perform a stroke operation on the text.
*/
DRAW_TEXT_STROKE,
/**
* Perform fill,then stroke operation on the text.
*/
DRAW_TEXT_BOTH,
}ps_draw_text_type;
/**
* \brief Text align mode for drawing text.
*/
typedef enum _ps_text_align {
/**
* Centers text horizontally in the rectangle.
*/
TEXT_ALIGN_CENTER = 0,
/**
* Justifies the text to the top of the rectangle.
*/
TEXT_ALIGN_TOP = 1,
/**
* Justifies the text to the bottom of the rectangle.
*/
TEXT_ALIGN_BOTTOM = 2,
/**
* Aligns text to left.
*/
TEXT_ALIGN_LEFT = 4,
/**
* Aligns text to right.
*/
TEXT_ALIGN_RIGHT = 8,
}ps_text_align;
/**
* \fn void ps_draw_text(ps_context* ctx, const ps_rect* area, const void* text, unsigned int length,
* ps_draw_text_type type, ps_text_align align)
* \brief Draw text in a rectangle area, using font object which is selected in graphic context.
*
* \param ctx Pointer to an existing context object.
* \param area The rectangle area which text to be drawn.
* \param text The unicode text string to be draw.
* \param length The length of the text string.
* \param type The rending type of text.
* \param align The text align mode.
*
* \sa ps_text_out_length, ps_wide_text_out_length
*/
PEXPORT void PICAPI ps_draw_text(ps_context* ctx, const ps_rect* area, const void* text,
unsigned int length, ps_draw_text_type type, ps_text_align align);
/**
* \fn ps_bool ps_get_glyph(ps_context* ctx, int ch, ps_glyph* glyph)
* \brief Get the glyph from a given character, using font object which is selected in graphic context.
*
* \param ctx Pointer to an existing context object.
* \param ch The character value.
* \param glyph Pointer to a structure to receiving the glyph.
*
* \return True if is success, otherwise False.
*
* \sa ps_show_glyphs, ps_get_path_from_glyph
*/
PEXPORT ps_bool PICAPI ps_get_glyph(ps_context* ctx, int ch, ps_glyph* glyph);
/**
* \fn void ps_show_glyphs(ps_context* ctx, float x, float y, ps_glyph* glyphs, unsigned int length)
* \brief Draw an array of glyphs at location in user space.
*
* \param ctx Pointer to an existing context object.
* \param x The X-coordinate at which to draw the glyphs.
* \param y The Y-coordinate at which to draw the glyphs.
* \param glyphs The array of glyphs.
* \param length The length of array.
*
* \sa ps_get_path_from_glyph
*/
PEXPORT void PICAPI ps_show_glyphs(ps_context* ctx, float x, float y,
ps_glyph* glyphs, unsigned int length);
/**
* \fn ps_bool ps_get_path_from_glyph(ps_context* ctx, const ps_glyph* glyph, ps_path* path)
* \brief Get the path from a given glyph object.
*
* \param ctx Pointer to an existing context object.
* \param glyph The glyph object.
* \param path Pointer to a structure to receiving the path.
*
* \return True if is success, otherwise False.
*
* \sa ps_show_glyphs
*/
PEXPORT ps_bool PICAPI ps_get_path_from_glyph(ps_context* ctx,
const ps_glyph* glyph, ps_path* path);
/**
* \fn ps_bool ps_glyph_get_extent(const ps_glyph* glyph, ps_size* rsize)
* \brief Get extent for a glyph object.
*
* \param glyph Pointer to an existing glyph object.
* \param rsize Pointer to a buffer to receiving the size.
*
* \return True if is success, otherwise False.
*
* \note To get extended error information, call \a ps_last_status.
*
* \sa ps_get_text_extent
*/
PEXPORT ps_bool PICAPI ps_glyph_get_extent(const ps_glyph* glyph, ps_size* rsize);
/** @} end of text functions*/
/**
* \defgroup transform Transform
* @{
*/
/**
* \fn void ps_translate(ps_context* ctx, float tx, float ty)
* \brief Changes the origin of the user coordinate system in graphic context.
*
* \param ctx Pointer to an existing context object.
* \param tx The amount, in pixels, which to translate in x direction.
* \param ty The amount, in pixels, which to translate in y direction.
*
* \sa ps_scale, ps_shear, ps_rotate, ps_identity, ps_transform
*/
PEXPORT void PICAPI ps_translate(ps_context* ctx, float tx, float ty);
/**
* \fn void ps_scale(ps_context* ctx, float sx, float sy)
* \brief Changes the scale of the user coordinate system in graphic context.
*
* \param ctx Pointer to an existing context object.
* \param sx The scale factor for the X dimension.
* \param sy The scale factor for the Y dimension.
*
* \sa ps_translate, ps_shear, ps_rotate, ps_identity, ps_transform
*/
PEXPORT void PICAPI ps_scale(ps_context* ctx, float sx, float sy);
/**
* \fn void ps_shear(ps_context* ctx, float shx, float shy)
* \brief Changes the shear of the user coordinate system in graphic context.
*
* \param ctx Pointer to an existing context object.
* \param shx The shear factor for the horizontal.
* \param shy The shear factor for the vertical.
*
* \sa ps_translate, ps_scale, ps_rotate, ps_identity, ps_transform
*/
PEXPORT void PICAPI ps_shear(ps_context* ctx, float shx, float shy);
/**
* \fn void ps_rotate(ps_context* ctx, float angle)
* \brief Rotates the user coordinate system in graphic context.
*
* \param ctx Pointer to an existing context object.
* \param angle The angle, in radians, which to rotate the specified context.
*
* \sa ps_translate, ps_scale, ps_shear, ps_identity, ps_transform
*/
PEXPORT void PICAPI ps_rotate(ps_context* ctx, float angle);
/**
* \fn void ps_identity(ps_context* ctx)
* \brief Reset the current transformation matrix to identity matrix.
*
* \param ctx Pointer to an existing context object.
*
* \sa ps_translate, ps_scale, ps_shear, ps_rotate, ps_transform
*/
PEXPORT void PICAPI ps_identity(ps_context* ctx);
/**
* \fn void ps_transform(ps_context* ctx, const ps_matrix* matrix)
* \brief Transforms the user coordinate system in graphic context using a specified matrix.
*
* \param ctx Pointer to an existing context object.
* \param matrix The matrix to apply to the specified context's current transformation matrix.
*
* \sa ps_translate, ps_scale, ps_shear, ps_rotate, ps_identity
*/
PEXPORT void PICAPI ps_transform(ps_context* ctx, const ps_matrix* matrix);
/**
* \fn void ps_set_matrix(ps_context* ctx, const ps_matrix* matrix)
* \brief Modifies the current transformation matrix to the given matrix.
*
* \param ctx Pointer to an existing context object.
* \param matrix The transformation matrix to be set.
*
* \sa ps_get_matrix
*/
PEXPORT void PICAPI ps_set_matrix(ps_context* ctx, const ps_matrix* matrix);
/**
* \fn ps_bool ps_get_matrix(ps_context* ctx, ps_matrix* matrix)
* \brief Get the current transformation matrix from graphic context.
*
* \param ctx Pointer to an existing context object.
* \param matrix Pointer to a matrix object to receiving the current transformation.
*
* \return True if is success, otherwise False.
*
* \sa ps_set_matrix
*/
PEXPORT ps_bool PICAPI ps_get_matrix(ps_context* ctx, ps_matrix* matrix);
/**
* \fn void ps_world_to_viewport(ps_context* ctx, ps_point* point)
* \brief Transform a coordinate from device space to user space.
*
* \param ctx Pointer to an existing context object.
* \param point The point which to be transformed.
*
* \sa ps_viewport_to_world
*/
PEXPORT void PICAPI ps_world_to_viewport(ps_context* ctx, ps_point* point);
/**
* \fn void ps_viewport_to_world(ps_context* ctx, ps_point* point)
* \brief Transform a coordinate from user space to device space.
*
* \param ctx Pointer to an existing context object.
* \param point The point which to be transformed.
*
* \sa ps_world_to_viewport
*/
PEXPORT void PICAPI ps_viewport_to_world(ps_context* ctx, ps_point* point);
/** @} end of transform functions*/
/**
* \defgroup matrix Matrix
* @{
*/
/**
* \fn ps_matrix* ps_matrix_create(void)
* \brief Create a identity matrix object.
*
* \return If the function succeeds, the return value is the pointer to a new matrix object.
* If the function fails, the return value is NULL.
*
* \note To get extended error information, call \a ps_last_status.
*
* \sa ps_matrix_create_init, ps_matrix_create_copy, ps_matrix_ref, ps_matrix_unref
*/
PEXPORT ps_matrix* PICAPI ps_matrix_create(void);
/**
* \fn ps_matrix* ps_matrix_create_init(float sx, float shy, float shx,
* float sy, float tx, float ty)
* \brief Create a matrix with given parameters.
*
* \param sx The horizontal scaling factor.
* \param shy The vertical skewing factor.
* \param shx The horizontal skewing factor.
* \param sy The vertical scaling factor.
* \param tx The horizontal translating factor.
* \param ty The vertical translating factor.
*
* \return If the function succeeds, the return value is the pointer to a new matrix object.
* If the function fails, the return value is NULL.
*
* \note To get extended error information, call \a ps_last_status.
*
* \sa ps_matrix_create, ps_matrix_create_copy, ps_matrix_ref, ps_matrix_unref
*/
PEXPORT ps_matrix* PICAPI ps_matrix_create_init(float sx, float shy, float shx,
float sy, float tx, float ty);
/**
* \fn ps_matrix* ps_matrix_create_copy(const ps_matrix* matrix)
* \brief Create a matrix copy from an exist one.
*
* \param matrix Pointer to an existing matrix object.
*
* \return If the function succeeds, the return value is the pointer to a new matrix object.
* If the function fails, the return value is NULL.
*
* \note To get extended error information, call \a ps_last_status.
*
* \sa ps_matrix_create_init, ps_matrix_create, ps_matrix_ref, ps_matrix_unref
*/
PEXPORT ps_matrix* PICAPI ps_matrix_create_copy(const ps_matrix* matrix);
/**
* \fn ps_matrix* ps_matrix_ref(ps_matrix* matrix)
* \brief Increases the reference count of the matrix by 1.
*
* \param matrix Pointer to an existing matrix object.
*
* \return If the function succeeds, the return value is the pointer to the matrix object.
* If the function fails, the return value is NULL.
*
* \note To get extended error information, call \a ps_last_status.
*
* \sa ps_matrix_create_init, ps_matrix_create, ps_matrix_create_copy, ps_matrix_unref
*/
PEXPORT ps_matrix* PICAPI ps_matrix_ref(ps_matrix* matrix);
/**
* \fn void ps_matrix_unref(ps_matrix* matrix)
* \brief Decrements the reference count for the matrix object.
* If the reference count on the matrix falls to 0, the matrix is freed.
*
* \param matrix Pointer to an existing matrix object.
*
* \sa ps_matrix_create_init, ps_matrix_create, ps_matrix_create_copy, ps_matrix_ref
*/
PEXPORT void PICAPI ps_matrix_unref(ps_matrix* matrix);
/**
* \fn void ps_matrix_init(ps_matrix* matrix, float sx, float shy,
* float shx, float sy, float tx, float ty)
* \brief Initialize an existing matrix object with given parameters.
*
* \param matrix Pointer to an existing matrix object.
* \param sx The horizontal scaling factor.
* \param shy The vertical skewing factor.
* \param shx The horizontal skewing factor.
* \param sy The vertical scaling factor.
* \param tx The horizontal translating factor.
* \param ty The vertical translating factor.
*
* \sa ps_matrix_translate, ps_matrix_scale, ps_matrix_shear, ps_matrix_rotate
*/
PEXPORT void PICAPI ps_matrix_init(ps_matrix* matrix, float sx, float shy,
float shx, float sy, float tx, float ty);
/**
* \fn void ps_matrix_translate(ps_matrix* matrix, float tx, float ty)
* \brief Modify a matrix by translating.
*
* \param matrix Pointer to an existing matrix object.
* \param tx The amount, in pixels, which to translate in x direction.
* \param ty The amount, in pixels, which to translate in y direction.
*
* \sa ps_matrix_scale, ps_matrix_shear, ps_matrix_rotate
*/
PEXPORT void PICAPI ps_matrix_translate(ps_matrix* matrix, float tx, float ty);
/**
* \fn void ps_matrix_scale(ps_matrix* matrix, float sx, float sy)
* \brief Modify a matrix by scaling.
*
* \param matrix Pointer to an existing matrix object.
* \param sx The scale factor for the X dimension.
* \param sy The scale factor for the Y dimension.
*
* \sa ps_matrix_translate, ps_matrix_shear, ps_matrix_rotate
*/
PEXPORT void PICAPI ps_matrix_scale(ps_matrix* matrix, float sx, float sy);
/**
* \fn void ps_matrix_rotate(ps_matrix* matrix, float angle)
* \brief Modify a matrix by rotating.
*
* \param matrix Pointer to an existing matrix object.
* \param angle The angle, in radians, which to rotate the specified matrix.
*
* \sa ps_matrix_translate, ps_matrix_shear, ps_matrix_scale
*/
PEXPORT void PICAPI ps_matrix_rotate(ps_matrix* matrix, float angle);
/**
* \fn void ps_matrix_shear(ps_matrix* matrix, float shx, float shy)
* \brief Modify a matrix by shearing.
*
* \param matrix Pointer to an existing matrix object.
* \param shx The shear factor for the horizontal.
* \param shy The shear factor for the vertical.
*
* \sa ps_matrix_translate, ps_matrix_scale, ps_matrix_rotate
*/
PEXPORT void PICAPI ps_matrix_shear(ps_matrix* matrix, float shx, float shy);
/**
* \fn void ps_matrix_invert(ps_matrix* matrix)
* \brief Modify a matrix by inverting.
*
* \param matrix Pointer to an existing matrix object.
*
* \sa ps_matrix_flip_x, ps_matrix_flip_y, ps_matrix_reset
*/
PEXPORT void PICAPI ps_matrix_invert(ps_matrix* matrix);
/**
* \fn void ps_matrix_reset(ps_matrix* matrix)
* \brief Reset a matrix to identity matrix.
*
* \param matrix Pointer to an existing matrix object.
*
* \sa ps_matrix_flip_x, ps_matrix_flip_y, ps_matrix_invert
*/
PEXPORT void PICAPI ps_matrix_reset(ps_matrix* matrix);
/**
* \fn void ps_matrix_flip_x(ps_matrix* matrix)
* \brief Flip a matrix in the horizontal direction.
*
* \param matrix Pointer to an existing matrix object.
*
* \sa ps_matrix_reset, ps_matrix_flip_y, ps_matrix_invert
*/
PEXPORT void PICAPI ps_matrix_flip_x(ps_matrix* matrix);
/**
* \fn void ps_matrix_flip_y(ps_matrix* matrix)
* \brief Flip a matrix in the vertical direction.
*
* \param matrix Pointer to an existing matrix object.
*
* \sa ps_matrix_reset, ps_matrix_flip_x, ps_matrix_invert
*/
PEXPORT void PICAPI ps_matrix_flip_y(ps_matrix* matrix);
/**
* \fn void ps_matrix_multiply(ps_matrix* result, const ps_matrix* a, const ps_matrix* b)
* \brief Multiplies the matrix in a and b together and stores the result in result.
*
* \param result Pointer to an existing matrix object in which to store the result.
* \param a Pointer to an existing matrix object.
* \param b Pointer to an existing matrix object.
*
* \sa ps_matrix_is_identity, ps_matrix_is_equal ps_matrix_get_determinant
*/
PEXPORT void PICAPI ps_matrix_multiply(ps_matrix* result, const ps_matrix* a, const ps_matrix* b);
/**
* \fn ps_bool ps_matrix_is_identity(const ps_matrix* matrix)
* \brief Checks whether the matrix is the identity transform matrix.
*
* \param matrix Pointer to an existing matrix object.
*
* \return True if is identity, otherwise False.
*
* \sa ps_matrix_is_equal, ps_matrix_get_determinant, ps_matrix_multiply
*/
PEXPORT ps_bool PICAPI ps_matrix_is_identity(const ps_matrix* matrix);
/**
* \fn ps_bool ps_matrix_is_equal(const ps_matrix* a, const ps_matrix* b)
* \brief Checks whether two matrix are equal.
*
* \param a Pointer to an existing matrix object.
* \param b Pointer to an existing matrix object.
*
* \return True if a and b are equal, otherwise False.
*
* \sa ps_matrix_is_identity, ps_matrix_get_determinant, ps_matrix_multiply
*/
PEXPORT ps_bool PICAPI ps_matrix_is_equal(const ps_matrix* a, const ps_matrix* b);
/**
* \fn float ps_matrix_get_determinant(const ps_matrix* matrix)
* \brief Return the determinant from a matrix.
*
* \param matrix Pointer to an existing matrix object.
*
* \return The determinant of the matrix.
*
* \sa ps_matrix_is_equal, ps_matrix_is_identity, ps_matrix_multiply
*/
PEXPORT float PICAPI ps_matrix_get_determinant(const ps_matrix* matrix);
/**
* \fn void ps_matrix_set_translate_factor(ps_matrix* matrix, float tx, float ty)
* \brief Set the translate factors to the matrix.
*
* \param matrix Pointer to an existing matrix object.
* \param tx The amount, in pixels, which the translate factor in x direction.
* \param ty The amount, in pixels, which the translate factor in y direction.
*
* \sa ps_matrix_get_translate_factor
*/
PEXPORT void PICAPI ps_matrix_set_translate_factor(ps_matrix* matrix, float tx, float ty);
/**
* \fn ps_bool ps_matrix_get_translate_factor(ps_matrix* matrix, float *tx, float *ty)
* \brief Get the translate factors from the matrix.
*
* \param matrix Pointer to an existing matrix object.
* \param tx Pointer to a buffer to receiving the translate factor in x direction.
* \param ty Pointer to a buffer to receiving the translate factor in y direction.
*
* \return True if is success, otherwise False.
*
* \sa ps_matrix_set_translate_factor
*/
PEXPORT ps_bool PICAPI ps_matrix_get_translate_factor(ps_matrix* matrix, float *tx, float *ty);
/**
* \fn void ps_matrix_set_scale_factor(ps_matrix* matrix, float sx, float sy)
* \brief Set the scale factors to the matrix.
*
* \param matrix Pointer to an existing matrix object.
* \param sx The scale factor in x dimension.
* \param sy The scale factor in y dimension.
*
* \sa ps_matrix_get_scale_factor
*/
PEXPORT void PICAPI ps_matrix_set_scale_factor(ps_matrix* matrix, float sx, float sy);
/**
* \fn ps_bool ps_matrix_get_scale_factor(ps_matrix* matrix, float *sx, float *sy)
* \brief Get the scale factors from the matrix.
*
* \param matrix Pointer to an existing matrix object.
* \param sx Pointer to a buffer to receiving the scale factor in x dimension.
* \param sy Pointer to a buffer to receiving the scale factor in y dimension.
*
* \return True if is success, otherwise False.
*
* \sa ps_matrix_set_scale_factor
*/
PEXPORT ps_bool PICAPI ps_matrix_get_scale_factor(ps_matrix* matrix, float *sx, float *sy);
/**
* \fn void ps_matrix_set_shear_factor(ps_matrix* matrix, float shx, float shy)
* \brief Set the shear factors to the matrix.
*
* \param matrix Pointer to an existing matrix object.
* \param shx The shear factor for the horizontal.
* \param shy The shear factor for the vertical.
*
* \sa ps_matrix_get_shear_factor
*/
PEXPORT void PICAPI ps_matrix_set_shear_factor(ps_matrix* matrix, float shx, float shy);
/**
* \fn ps_bool ps_matrix_get_shear_factor(ps_matrix* matrix, float *shx, float *shy)
* \brief Get the shear factors from the matrix.
*
* \param matrix Pointer to an existing matrix object.
* \param shx Pointer to a buffer to receiving the shear factor in horizontal.
* \param shy Pointer to a buffer to receiving the shear factor in vertical.
*
* \return True if is success, otherwise False.
*
* \sa ps_matrix_set_shear_factor
*/
PEXPORT ps_bool PICAPI ps_matrix_get_shear_factor(ps_matrix* matrix, float *shx, float *shy);
/**
* \fn void ps_matrix_transform_point(const ps_matrix* matrix, ps_point* point)
* \brief Transform an existing point using the matrix.
*
* \param matrix Pointer to an existing matrix object.
* \param point An existing point which will be transformed.
*
* \sa ps_matrix_transform_rect, ps_matrix_transform_path
*/
PEXPORT void PICAPI ps_matrix_transform_point(const ps_matrix* matrix, ps_point* point);
/**
* \fn void ps_matrix_transform_rect(const ps_matrix* matrix, ps_rect* rect)
* \brief Transform an existing rectangle using the matrix.
*
* \param matrix Pointer to an existing matrix object.
* \param rect An existing rectangle which will be transformed.
*
* \sa ps_matrix_transform_point, ps_matrix_transform_path
*/
PEXPORT void PICAPI ps_matrix_transform_rect(const ps_matrix* matrix, ps_rect* rect);
/**
* \fn void ps_matrix_transform_path(const ps_matrix* matrix, ps_path* path)
* \brief Transform an existing path using the matrix.
*
* \param matrix Pointer to an existing matrix object.
* \param path An existing path which will be transformed.
*
* \sa ps_matrix_transform_point, ps_matrix_transform_rect
*/
PEXPORT void PICAPI ps_matrix_transform_path(const ps_matrix* matrix, ps_path* path);
/** @} end of matrix functions*/
/**
* \defgroup geometry Geometry
* @{
*/
/**
* \fn void ps_new_path(ps_context* ctx)
* \brief Create a new empty path in the graphic context, clear the old one.
*
* \param ctx Pointer to an existing context object.
*
* \sa ps_new_sub_path, ps_set_path, ps_get_path, ps_close_path, ps_add_sub_path
*/
PEXPORT void PICAPI ps_new_path(ps_context* ctx);
/**
* \fn void ps_new_sub_path(ps_context* ctx)
* \brief Close the current path, and add a new empty sub path in the graphic context.
*
* \param ctx Pointer to an existing context object.
*
* \sa ps_new_path, ps_set_path, ps_get_path, ps_close_path, ps_add_sub_path
*/
PEXPORT void PICAPI ps_new_sub_path(ps_context* ctx);
/**
* \fn void ps_add_sub_path(ps_context* ctx, const ps_path* path)
* \brief Add a new sub path to current path in the graphic context.
*
* \param ctx Pointer to an existing context object.
* \param path The path will be add to graphic context.
*
* \sa ps_new_path, ps_new_sub_path, ps_set_path, ps_get_path, ps_close_path
*/
PEXPORT void PICAPI ps_add_sub_path(ps_context* ctx, const ps_path* path);
/**
* \fn void ps_set_path(ps_context* ctx, const ps_path* path)
* \brief Replace the current path in the graphic context.
*
* \param ctx Pointer to an existing context object.
* \param path The path will be set to graphic context.
*
* \sa ps_new_path, ps_new_sub_path, ps_get_path, ps_close_path, ps_add_sub_path
*/
PEXPORT void PICAPI ps_set_path(ps_context* ctx, const ps_path* path);
/**
* \fn ps_bool ps_get_path(ps_context* ctx, ps_path* path)
* \brief Get the current path in the graphic context.
*
* \param ctx Pointer to an existing context object.
* \param path Pointer to a object to receiving the path.
*
* \return True if is success, otherwise False.
*
* \sa ps_new_path, ps_new_sub_path, ps_close_path, ps_set_path, ps_add_sub_path
*/
PEXPORT ps_bool PICAPI ps_get_path(ps_context* ctx, ps_path* path);
/**
* \fn void ps_close_path(ps_context* ctx)
* \brief Close the current path in the graphic context.
*
* \param ctx Pointer to an existing context object.
*
* \sa ps_new_path, ps_new_sub_path, ps_set_path, ps_get_path, ps_add_sub_path
*/
PEXPORT void PICAPI ps_close_path(ps_context* ctx);
/**
* \fn void ps_move_to(ps_context* ctx, const ps_point* point)
* \brief Begin a new sub path, and set the current point.
*
* \param ctx Pointer to an existing context object.
* \param point The point which will be set.
*
* \sa ps_line_to, ps_bezier_curve_to, ps_quad_curve_to
* ps_arc, ps_tangent_arc, ps_rectangle, ps_rounded_rect, ps_ellipse
*/
PEXPORT void PICAPI ps_move_to(ps_context* ctx, const ps_point* point);
/**
* \fn void ps_line_to(ps_context* ctx, const ps_point* point)
* \brief Add a line to the current path from the current point to given point.
*
* \param ctx Pointer to an existing context object.
* \param point The point which will line to.
*
* \sa ps_move_to, ps_bezier_curve_to, ps_quad_curve_to
* ps_arc, ps_tangent_arc, ps_rectangle, ps_rounded_rect, ps_ellipse
*/
PEXPORT void PICAPI ps_line_to(ps_context* ctx, const ps_point* point);
/**
* \fn void ps_bezier_curve_to(ps_context* ctx, const ps_point* fcp,
* const ps_point* scp, const ps_point* ep)
* \brief Add a cubic bezier spline to the current path from current point to end point.
*
* \param ctx Pointer to an existing context object.
* \param fcp The first control point of the curve.
* \param scp The second control point of the curve.
* \param ep The end point of the curve.
*
* \sa ps_move_to, ps_line_to, ps_quad_curve_to, ps_arc,
* ps_tangent_arc, ps_rectangle, ps_rounded_rect, ps_ellipse
*/
PEXPORT void PICAPI ps_bezier_curve_to(ps_context* ctx, const ps_point* fcp,
const ps_point* scp, const ps_point* ep);
/**
* \fn void ps_quad_curve_to(ps_context* ctx, const ps_point* cp, const ps_point* ep)
* \brief Add a quadratic bezier spline to the current path from current point to end point.
*
* \param ctx Pointer to an existing context object.
* \param cp The control point of the curve.
* \param ep The end point of the curve.
*
* \sa ps_move_to, ps_line_to, ps_bezier_curve_to, ps_arc,
* ps_tangent_arc, ps_rectangle, ps_rounded_rect, ps_ellipse
*/
PEXPORT void PICAPI ps_quad_curve_to(ps_context* ctx, const ps_point* cp, const ps_point* ep);
/**
* \fn void ps_arc(ps_context* ctx, const ps_point* cp, float radius,
* float sangle, float eangle, ps_bool clockwise)
* \brief Add a circular arc to the current path.
*
* \param ctx Pointer to an existing context object.
* \param cp The center point of the arc.
* \param radius The radius of the arc.
* \param sangle The start angle, in radians.
* \param eangle The end angle, in radians.
* \param clockwise True is clockwise, False is counter clockwise.
*
* \sa ps_move_to, ps_line_to, ps_bezier_curve_to, ps_quad_curve_to,
* ps_tangent_arc, ps_rectangle, ps_rounded_rect, ps_ellipse
*/
PEXPORT void PICAPI ps_arc(ps_context* ctx, const ps_point* cp, float radius,
float sangle, float eangle, ps_bool clockwise);
/**
* \fn void ps_tangent_arc(ps_context* ctx, const ps_rect* rect, float sangle, float sweep)
* \brief Add a circular arc which is inner tangent from a rectangle.
*
* \param ctx Pointer to an existing context object.
* \param rect The rectangle which the arc to fit in.
* \param sangle The start angle, in radians.
* \param sweep The sweep angle, in radians.
*
* \sa ps_move_to, ps_line_to, ps_bezier_curve_to, ps_quad_curve_to,
* ps_arc, ps_rectangle, ps_rounded_rect, ps_ellipse
*/
PEXPORT void PICAPI ps_tangent_arc(ps_context* ctx, const ps_rect* rect, float sangle, float sweep);
/**
* \fn void ps_rectangle(ps_context* ctx, const ps_rect* rect)
* \brief Add a rectangle to the current path.
*
* \param ctx Pointer to an existing context object.
* \param rect The rectangle which will be added.
*
* \sa ps_move_to, ps_line_to, ps_bezier_curve_to, ps_quad_curve_to,
* ps_arc, ps_tangent_arc, ps_rounded_rect, ps_ellipse
*/
PEXPORT void PICAPI ps_rectangle(ps_context* ctx, const ps_rect* rect);
/**
* \fn void ps_rounded_rect(ps_context* ctx, const ps_rect* rect, float ltx, float lty, float rtx,
* float rty, float lbx, float lby, float rbx, float rby)
* \brief Add a rounded rectangle to the current path.
*
* \param ctx Pointer to an existing context object.
* \param rect The rectangle which will be added.
* \param ltx The left top horizontal radius.
* \param lty The left top vertical radius.
* \param rtx The right top horizontal radius.
* \param rty The right top vertical radius.
* \param lbx The left bottom horizontal radius.
* \param lby The left bottom vertical radius.
* \param rbx The right bottom horizontal radius.
* \param rby The right bottom vertical radius.
*
* \sa ps_move_to, ps_line_to, ps_bezier_curve_to, ps_quad_curve_to,
* ps_arc, ps_tangent_arc, ps_rectangle, ps_ellipse
*/
PEXPORT void PICAPI ps_rounded_rect(ps_context* ctx, const ps_rect* rect, float ltx,
float lty, float rtx, float rty, float lbx, float lby, float rbx, float rby);
/**
* \fn void ps_ellipse(ps_context* ctx, const ps_rect* rect)
* \brief Adds an ellipse to the current path which fits inside the specified rectangle.
*
* \param ctx Pointer to an existing context object.
* \param rect The rectangle which the ellipse to fit in.
*
* \sa ps_move_to, ps_line_to, ps_bezier_curve_to, ps_quad_curve_to,
* ps_arc, ps_tangent_arc, ps_rectangle, ps_rounded_rect
*/
PEXPORT void PICAPI ps_ellipse(ps_context* ctx, const ps_rect* rect);
/** @} end of geometry functions*/
/**
* \defgroup path Path
* @{
*/
/**
* \fn ps_path* ps_path_create(void)
* \brief Create a new empty path object.
*
* \return If the function succeeds, the return value is the pointer to a new path object.
* If the function fails, the return value is NULL.
*
* \note To get extended error information, call \a ps_last_status.
*
* \sa ps_path_create_copy, ps_path_ref, ps_path_unref
*/
PEXPORT ps_path* PICAPI ps_path_create(void);
/**
* \fn ps_path* ps_path_create_copy(const ps_path* path)
* \brief Create a copy from an existing path object.
*
* \param path Pointer to an existing path object.
*
* \return If the function succeeds, the return value is the pointer to a new path object.
* If the function fails, the return value is NULL.
*
* \note To get extended error information, call \a ps_last_status.
*
* \sa ps_path_create, ps_path_ref, ps_path_unref
*/
PEXPORT ps_path* PICAPI ps_path_create_copy(const ps_path* path);
/**
* \fn ps_path* ps_path_ref(ps_path* path)
* \brief Increases the reference count of the path by 1.
*
* \param path Pointer to an existing path object.
*
* \return If the function succeeds, the return value is the pointer to the path object.
* If the function fails, the return value is NULL.
*
* \note To get extended error information, call \a ps_last_status.
*
* \sa ps_path_create, ps_path_create_copy, ps_path_unref
*/
PEXPORT ps_path* PICAPI ps_path_ref(ps_path* path);
/**
* \fn void ps_path_unref(ps_path* path)
* \brief Decrements the reference count for the path object.
* If the reference count on the path falls to 0, the path is freed.
*
* \param path Pointer to an existing path object.
*
* \sa ps_path_create, ps_path_create_copy, ps_path_ref
*/
PEXPORT void PICAPI ps_path_unref(ps_path* path);
/**
* \fn void ps_path_move_to(ps_path* path, const ps_point* point)
* \brief Begin a new sub path, and set the current point in the path.
*
* \param path Pointer to an existing path object.
* \param point The point which will be set.
*
* \sa ps_path_line_to, ps_path_bezier_to, ps_path_quad_to
* ps_path_arc_to, ps_path_tangent_arc_to
*/
PEXPORT void PICAPI ps_path_move_to(ps_path* path, const ps_point* point);
/**
* \fn void ps_path_line_to(ps_path* path, const ps_point* point)
* \brief Add a line to the path from the current point to given point.
*
* \param path Pointer to an existing path object.
* \param point The point which will be set.
*
* \sa ps_path_move_to, ps_path_bezier_to, ps_path_quad_to
* ps_path_arc_to, ps_path_tangent_arc_to
*/
PEXPORT void PICAPI ps_path_line_to(ps_path* path, const ps_point* point);
/**
* \fn void ps_path_tangent_arc_to(ps_path* path, float radius, const ps_point* tp, const ps_point* ep)
* \brief Add an arc to the path which tangent at two line.
*
* \param path Pointer to an existing path object.
* \param radius The radius of the arc.
* \param tp The point which the first tangent line from current point to.
* \param ep The point which the second tangent line from \a tp to.
*
* \sa ps_path_move_to, ps_path_bezier_to, ps_path_quad_to
* ps_path_arc_to, ps_path_line_to
*/
PEXPORT void PICAPI ps_path_tangent_arc_to(ps_path* path, float radius,
const ps_point* tp, const ps_point* ep);
/**
* \fn void ps_path_arc_to(ps_path* path, float radiusX, float radiusY, float angle,
* ps_bool large_arc, ps_bool clockwise, const ps_point* ep)
* \brief Add an arc to the path, using radius, angle and end point.
*
* \param path Pointer to an existing path object.
* \param radiusX The horizontal radius of arc.
* \param radiusY The vertical radius of arc.
* \param angle The angle of arc, in radians.
* \param large_arc True is large arc, False is small arc.
* \param clockwise True is clockwise, False is counter clockwise.
* \param ep The end point of the arc.
*
* \sa ps_path_move_to, ps_path_bezier_to, ps_path_quad_to
* ps_path_tangent_arc_to, ps_path_line_to
*/
PEXPORT void PICAPI ps_path_arc_to(ps_path* path, float radiusX, float radiusY, float angle,
ps_bool large_arc, ps_bool clockwise, const ps_point* ep);
/**
* \fn void ps_path_bezier_to(ps_path* path, const ps_point* fcp, const ps_point* scp, const ps_point* ep)
* \brief Add a cubic bezier spline to the path from current point to end point.
*
* \param path Pointer to an existing path object.
* \param fcp The first control point of the curve.
* \param scp The second control point of the curve.
* \param ep The end point of the curve.
*
* \sa ps_path_move_to, ps_path_arc_to, ps_path_quad_to
* ps_path_tangent_arc_to, ps_path_line_to
*/
PEXPORT void PICAPI ps_path_bezier_to(ps_path* path, const ps_point* fcp,
const ps_point* scp, const ps_point* ep);
/**
* \fn void ps_path_quad_to(ps_path* path, const ps_point* cp, const ps_point* ep)
* \brief Add a quadratic bezier spline to the path from current point to end point.
*
* \param path Pointer to an existing path object.
* \param cp The control point of the curve.
* \param ep The end point of the curve.
*
* \sa ps_path_move_to, ps_path_arc_to, ps_path_bezier_to
* ps_path_tangent_arc_to, ps_path_line_to
*/
PEXPORT void PICAPI ps_path_quad_to(ps_path* path, const ps_point* cp, const ps_point* ep);
/**
* \fn void ps_path_sub_close(ps_path* path)
* \brief Close the sub path, and begin a new one.
*
* \param path Pointer to an existing path object.
*
* \sa ps_path_get_length, ps_path_clear, ps_path_is_empty
*/
PEXPORT void PICAPI ps_path_sub_close(ps_path* path);
/**
* \fn float ps_path_get_length(const ps_path* path)
* \brief Return The length of the path.
*
* \param path Pointer to an existing path object.
*
* \return If the function succeeds, the return value is the length of the path object.
* If the function fails, the return value is 0.
*
* \note To get extended error information, call \a ps_last_status.
*
* \sa ps_path_sub_close, ps_path_clear, ps_path_is_empty
*/
PEXPORT float PICAPI ps_path_get_length(const ps_path* path);
/**
* \fn void ps_path_clear(ps_path* path)
* \brief Clear the path to empty.
*
* \param path Pointer to an existing path object.
*
* \sa ps_path_sub_close, ps_path_get_length, ps_path_is_empty
*/
PEXPORT void PICAPI ps_path_clear(ps_path* path);
/**
* \fn ps_bool ps_path_is_empty(const ps_path* path)
* \brief Checks whether the path is empty.
*
* \param path Pointer to an existing path object.
*
* \sa ps_path_sub_close, ps_path_get_length, ps_path_clear
*/
PEXPORT ps_bool PICAPI ps_path_is_empty(const ps_path* path);
/**
* \fn unsigned int ps_path_get_vertex_count(const ps_path* path)
* \brief Return the count of vertices in the path.
*
* \param path Pointer to an existing path object.
*
* \return If the function succeeds, the return value is the vertices count in the path object.
* If the function fails, the return value is 0.
*
* \note To get extended error information, call \a ps_last_status.
*
* \sa ps_path_get_vertex, ps_path_bounding_rect, ps_path_contains, ps_path_stroke_contains
*/
PEXPORT unsigned int PICAPI ps_path_get_vertex_count(const ps_path* path);
/**
* \brief Path command for vertices.
*/
typedef enum _ps_path_cmd {
/**
* Stop command.
*/
PATH_CMD_STOP = 0,
/**
* Move to command.
*/
PATH_CMD_MOVE_TO = 1,
/**
* Line to command.
*/
PATH_CMD_LINE_TO = 2,
/**
* Quad curve to command.
*/
PATH_CMD_CURVE3 = 3,
/**
* Bezier curve to command.
*/
PATH_CMD_CURVE4 = 4,
/**
* End polyline command.
*/
PATH_CMD_END_POLY = 0x0F,
}ps_path_cmd;
/**
* \fn ps_path_cmd ps_path_get_vertex(const ps_path* path, unsigned int index, ps_point * point)
* \brief Get a vertex from the path by index, and return the vertex command.
*
* \param path Pointer to an existing path object.
* \param index The index of the vertex.
* \param point Pointer to a structure to receiving the vertex.
*
* \return If the function succeeds, the return value is the command of the vertex.
* If the function fails, the return value is PATH_CMD_STOP.
*
* \note To get extended error information, call \a ps_last_status.
*
* \sa ps_path_get_vertex_count, ps_path_bounding_rect, ps_path_contains, ps_path_stroke_contains
*/
PEXPORT ps_path_cmd PICAPI ps_path_get_vertex(const ps_path* path,
unsigned int index, ps_point * point);
/**
* \fn ps_bool ps_path_bounding_rect(const ps_path* path, ps_rect* rect)
* \brief Get the bounding rectangle of the path.
*
* \param path Pointer to an existing path object.
* \param rect Pointer to a buffer to receiving the rect.
*
* \return True if is success, otherwise False.
*
* \note To get extended error information, call \a ps_last_status.
*
* \sa ps_path_get_vertex_count, ps_path_get_vertex, ps_path_contains, ps_path_stroke_contains
*/
PEXPORT ps_bool PICAPI ps_path_bounding_rect(const ps_path* path, ps_rect* rect);
/**
* \fn ps_bool ps_path_contains(const ps_path* path, const ps_point* point, ps_fill_rule rule)
* \brief Check whether a point is contained in the path by fill method.
*
* \param path Pointer to an existing path object.
* \param point The point to be checked.
* \param rule The filling rule for the path.
*
* \return True if the point is contained, otherwise False.
*
* \sa ps_path_get_vertex_count, ps_path_get_vertex, ps_path_bounding_rect, ps_path_stroke_contains
*/
PEXPORT ps_bool PICAPI ps_path_contains(const ps_path* path,
const ps_point* point, ps_fill_rule rule);
/**
* \fn ps_bool ps_path_stroke_contains(const ps_path* path, const ps_point* point, float width)
* \brief Check whether a point is contained in the path by stroke method.
*
* \param path Pointer to an existing path object.
* \param point The point to be checked.
* \param width The line width to use, in pixels, must be greater than 0.
*
* \return True if the point is contained, otherwise False.
*
* \sa ps_path_get_vertex_count, ps_path_get_vertex, ps_path_bounding_rect, ps_path_contains
*/
PEXPORT ps_bool PICAPI ps_path_stroke_contains(const ps_path* path,
const ps_point* point, float width);
/**
* \fn void ps_path_add_line(ps_path* path, const ps_point* p1, const ps_point* p2)
* \brief Add a line to the path.
*
* \param path Pointer to an existing path object.
* \param p1 The start point for the line.
* \param p2 The end point for the line.
*
* \sa ps_path_add_arc, ps_path_add_rect, ps_path_add_ellipse, ps_path_add_rounded_rect, ps_path_add_sub_path
*/
PEXPORT void PICAPI ps_path_add_line(ps_path* path, const ps_point* p1, const ps_point* p2);
/**
* \fn void ps_path_add_arc(ps_path* path, const ps_point* cp, float radius, float sangle,
* float eangle, ps_bool clockwise)
* \brief Add a arc to the path.
*
* \param path Pointer to an existing path object.
* \param cp The center point of the arc.
* \param radius The radius of the arc.
* \param sangle The start angle, in radians.
* \param eangle The end angle, in radians.
* \param clockwise True is clockwise, False is counter clockwise.
*
* \sa ps_path_add_line, ps_path_add_rect, ps_path_add_ellipse, ps_path_add_rounded_rect, ps_path_add_sub_path
*/
PEXPORT void PICAPI ps_path_add_arc(ps_path* path, const ps_point* cp, float radius,
float sangle, float eangle, ps_bool clockwise);
/**
* \fn void ps_path_add_rect(ps_path* path, const ps_rect* rect)
* \brief Add a rectangle to the path.
*
* \param path Pointer to an existing path object.
* \param rect The rectangle to be added.
*
* \sa ps_path_add_arc, ps_path_add_line, ps_path_add_ellipse, ps_path_add_rounded_rect, ps_path_add_sub_path
*/
PEXPORT void PICAPI ps_path_add_rect(ps_path* path, const ps_rect* rect);
/**
* \fn void ps_path_add_ellipse(ps_path* path, const ps_rect* rect)
* \brief Add an ellipse to the path.
*
* \param path Pointer to an existing path object.
* \param rect The rectangle to enclose the ellipse.
*
* \sa ps_path_add_arc, ps_path_add_line, ps_path_add_rect, ps_path_add_rounded_rect, ps_path_add_sub_path
*/
PEXPORT void PICAPI ps_path_add_ellipse(ps_path* path, const ps_rect* rect);
/**
* \fn void ps_path_add_rounded_rect(ps_path* path, const ps_rect* rect, float ltx, float lty,
* float rtx, float rty, float lbx, float lby, float rbx, float rby)
* \brief Add a rounded rectangle to the path.
*
* \param path Pointer to an existing path object.
* \param rect The rectangle which will be added.
* \param ltx The left top horizontal radius.
* \param lty The left top vertical radius.
* \param rtx The right top horizontal radius.
* \param rty The right top vertical radius.
* \param lbx The left bottom horizontal radius.
* \param lby The left bottom vertical radius.
* \param rbx The right bottom horizontal radius.
* \param rby The right bottom vertical radius.
*
* \sa ps_path_add_arc, ps_path_add_line, ps_path_add_rect, ps_path_add_ellipse, ps_path_add_sub_path
*/
PEXPORT void PICAPI ps_path_add_rounded_rect(ps_path* path, const ps_rect* rect, float ltx,
float lty, float rtx, float rty, float lbx, float lby, float rbx, float rby);
/**
* \fn void ps_path_add_sub_path(ps_path* path, const ps_path* spath)
* \brief Add an sub path to the path.
*
* \param path Pointer to an existing path object.
* \param spath The path will be added.
*
* \sa ps_path_add_arc, ps_path_add_line, ps_path_add_rect, ps_path_add_rounded_rect, ps_path_add_ellipse
*/
PEXPORT void PICAPI ps_path_add_sub_path(ps_path* path, const ps_path* spath);
/**
* \brief Path clipping operations.
*/
typedef enum _ps_path_op {
/**
* Union.
*/
PATH_OP_UNION,
/**
* Intersection.
*/
PATH_OP_INTERSECT,
/**
* Exclusive or.
*/
PATH_OP_XOR,
/**
* Difference.
*/
PATH_OP_DIFF,
}ps_path_operation;
/**
* \fn void ps_path_clipping(ps_path* result, ps_path_operation op, const ps_path* a, const ps_path* b)
*
* \brief Clipping two path with the operation and get the result path.
*
* \param result Pointer to an existing path object for result.
* \param op The specified operation for clipping.
* \param a The source path for clipping.
* \param b The path which will be clipping.
*
* \sa ps_path_get_vertex, ps_path_get_vertex_count
*/
PEXPORT void PICAPI ps_path_clipping(ps_path* result, ps_path_operation op,
const ps_path* a, const ps_path* b);
/** @} end of path functions*/
/** @} end of graphic functions*/
#ifdef __cplusplus
}
#endif /* __cplusplus */
#endif /*_PICASSO_H_*/
Reference in New Issue View Git Blame Copy Permalink