Functions
PEXPORT ps_image *PICAPI	ps_image_create (ps_color_format fmt, int width, int height)
	Create a new image using the given parameters.
PEXPORT ps_image *PICAPI	ps_image_create_with_data (ps_byte *data, ps_color_format fmt, int width, int height, int pitch)
	Create a new image using a given address in memory.
PEXPORT ps_image *PICAPI	ps_image_create_from_data (ps_byte *data, ps_color_format fmt, int width, int height, int pitch)
	Create a new image using a copy of given address in memory.
PEXPORT ps_image *PICAPI	ps_image_create_compatible (const ps_canvas *canvas, int width, int height)
	Create a new image to compatible with an existing canvas.
PEXPORT ps_image *PICAPI	ps_image_create_from_canvas (ps_canvas canvas, const ps_rect rect)
	Create a new image using part of an existing canvas in same pixel buffer.
PEXPORT ps_image *PICAPI	ps_image_create_from_image (ps_image img, const ps_rect rect)
	Create a new image using part of an existing ps_image object in same pixel buffer.
PEXPORT ps_image *PICAPI	ps_image_ref (ps_image *img)
	Increases the reference count of the image by 1.
PEXPORT void PICAPI	ps_image_unref (ps_image *img)
	Decrements the reference count for the image object. If the reference count on the image falls to 0, the image is freed.
PEXPORT void PICAPI	ps_image_set_allow_transparent (ps_image *img, ps_bool allow)
	Set whether the image allowed be transparent, False is default.
PEXPORT void PICAPI	ps_image_set_transparent_color (ps_image img, const ps_color color)
	Set the transparent color for the image.
PEXPORT ps_bool PICAPI	ps_image_get_size (const ps_image img, ps_size rsize)
	Return the size of the image.
PEXPORT ps_color_format PICAPI	ps_image_get_format (const ps_image *img)
	Return the pixel format of the image.

Function Documentation

ps_image * ps_image_create	(	ps_color_format	fmt,
		int	width,
		int	height
	)

Create a new image using the given parameters.

Parameters:

fmt	The Pixel format to use for the image.
width	The width, in pixels, of the required image.
height	The height, in pixels, of the required image.

Returns:: 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 ps_last_status.

See also:: 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

ps_image * ps_image_create_compatible	(	const ps_canvas *	canvas,
		int	width,
		int	height
	)

Create a new image to compatible with an existing canvas.

Parameters:

canvas	A pointer to an existing canvas.
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.
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.

Returns:: 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 ps_last_status.

See also:: ps_image_create, ps_image_create_with_data, ps_image_create_from_canvas, ps_image_create_from_image, ps_image_ref, ps_image_unref

ps_image * ps_image_create_from_canvas	(	ps_canvas *	canvas,
		const ps_rect *	rect
	)

Create a new image using part of an existing canvas in same pixel buffer.

Parameters:

canvas	A pointer to an existing canvas.
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.

Returns:: 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 ps_last_status.

See also:: 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

ps_image * ps_image_create_from_data	(	ps_byte *	data,
		ps_color_format	fmt,
		int	width,
		int	height,
		int	pitch
	)

Create a new image using a copy of given address in memory.

Parameters:

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.
fmt	The Pixel format to use for the image.
width	The width, in pixels, of the required image.
height	The height, in pixels, of the required image.
pitch	The number of bytes per row, of the required image.

Returns:: 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 ps_last_status.

See also:: 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

ps_image * ps_image_create_from_image	(	ps_image *	img,
		const ps_rect *	rect
	)

Create a new image using part of an existing ps_image object in same pixel buffer.

Parameters:

img	A pointer to an existing ps_image object.
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.

Returns:: 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 ps_last_status.

See also:: 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

ps_image * ps_image_create_with_data	(	ps_byte *	data,
		ps_color_format	fmt,
		int	width,
		int	height,
		int	pitch
	)

Create a new image using a given address in memory.

Parameters:

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.
fmt	The Pixel format to use for the image.
width	The width, in pixels, of the required image.
height	The height, in pixels, of the required image.
pitch	The number of bytes per row, of the required image.

Returns:: 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 ps_last_status.

See also:: 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

ps_color_format ps_image_get_format ( const ps_image * img )

Return the pixel format of the image.

Parameters:

img	Pointer to an existing image object.

Returns:: 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 ps_last_status.

See also:: ps_image_get_size, ps_image_set_allow_transparent

ps_bool ps_image_get_size	(	const ps_image *	img,
		ps_size *	rsize
	)

Return the size of the image.

Parameters:

img	Pointer to an existing image object.
rsize	Pointer to a buffer to receiving the size.

Returns:: True if is success, otherwise False.

Note:: To get extended error information, call ps_last_status.

See also:: ps_image_get_format, ps_image_set_allow_transparent

ps_image * ps_image_ref ( ps_image * img )

Increases the reference count of the image by 1.

Parameters:

img	Pointer to an existing image object.

Returns:: 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 ps_last_status.

See also:: 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

void ps_image_set_allow_transparent	(	ps_image *	img,
		ps_bool	allow
	)

Set whether the image allowed be transparent, False is default.

Parameters:

img	Pointer to an existing image object.
allow	Boolean value whether transparent is allowed.

See also:: ps_image_get_format, ps_image_get_size

void ps_image_set_transparent_color	(	ps_image *	img,
		const ps_color *	color
	)

Set the transparent color for the image.

Parameters:

img	Pointer to an existing image object.
color	The color for the transparent, NULL for disable.

See also:: ps_image_get_format, ps_image_get_size

void ps_image_unref ( ps_image * img )

Decrements the reference count for the image object. If the reference count on the image falls to 0, the image is freed.

Parameters:

img	Pointer to an existing image object.

See also:: 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

Functions

Function Documentation