PnImage

Name

PnImage -- an image that can be acted upon by actuators

Synopsis


#include <pn/pn.h>


struct      PnImage;
PnImage*    pn_image_new                    (void);

void        pn_image_set_size               (PnImage *image,
                                             guint width,
                                             guint height);
guint       pn_image_get_width              (PnImage *image);
guint       pn_image_get_height             (PnImage *image);
guint       pn_image_get_pitch              (PnImage *image);
void        pn_image_set_render_mode        (PnImage *image,
                                             PnBlendMode render_mode);
enum        PnBlendMode;
struct      PnColor;
void        pn_image_set_transform_mode     (PnImage *image,
                                             PnBlendMode transform_mode);

PnColor*    pn_image_get_image_buffer       (PnImage *image);
PnColor*    pn_image_get_transform_buffer   (PnImage *image);

void        pn_image_render_pixel           (PnImage *image,
                                             guint x,
                                             guint y,
                                             PnColor color);
void        pn_image_render_pixel_by_offset (PnImage *image,
                                             guint offset,
                                             PnColor color);
void        pn_image_render_line            (PnImage *image,
                                             guint x0,
                                             guint y0,
                                             guint x1,
                                             guint y1,
                                             PnColor color);

void        pn_image_apply_transform        (PnImage *image);
void        pn_image_render_image           (PnImage *image,
                                             PnImage *src,
                                             PnBlendMode blend_mode);

Object Hierarchy


  GObject
   +----PnObject
         +----PnImage

Description

PnImage objects contain two buffers containing images. The 'image buffer' is the main, or 'front', buffer. This is where all rendering is done, and where the actual image is. The 'transform buffer' is a temporary buffer that is used by actuators that affect every pixel in the image. These transform actuators must first set the value of every pixel in the transform buffer; they then must call pn_image_apply_transform() to render the transform buffer onto the image buffer.

Details

struct PnImage

struct PnImage;


pn_image_new ()

PnImage*    pn_image_new                    (void);

Creates a new PnImage object

Returns : The new PnImage object


pn_image_set_size ()

void        pn_image_set_size               (PnImage *image,
                                             guint width,
                                             guint height);

Sets the size of the image contained in a PnImage object

image : a PnImage
width : the new width of the image
height : the new height of the image


pn_image_get_width ()

guint       pn_image_get_width              (PnImage *image);

Gets the width of a PnImage

image : a PnImage
Returns : The width of the image


pn_image_get_height ()

guint       pn_image_get_height             (PnImage *image);

Gets the height of a PnImage

image : a PnImage
Returns : The height of the image


pn_image_get_pitch ()

guint       pn_image_get_pitch              (PnImage *image);

Gets the pitch (width in bytes) of a PnImage

image : a PnImage
Returns : The pitch of the image


pn_image_set_render_mode ()

void        pn_image_set_render_mode        (PnImage *image,
                                             PnBlendMode render_mode);

Sets the blend mode to be used by render functions. The render functions are pn_image_render_pixel(), pn_image_render_pixel_by_offset(), and pn_image_render_line().

image : a PnImage
render_mode : the blend mode to use


enum PnBlendMode

typedef enum
{
  PN_BLEND_MODE_IGNORE, /* Ignore the source image */
  PN_BLEND_MODE_REPLACE, /* Replace the destination image with the source */
  PN_BLEND_MODE_5050, /* Use the mean of the source and destination images */
  PN_BLEND_MODE_LAST /* INVALID */
} PnBlendMode;


struct PnColor

struct PnColor
{
  guint8 red;
  guint8 green;
  guint8 blue;
  guint8 unused;
};


pn_image_set_transform_mode ()

void        pn_image_set_transform_mode     (PnImage *image,
                                             PnBlendMode transform_mode);

Sets the blend mode to be used by pn_image_apply_transform().

image : a PnImage
transform_mode : the blend mode to use


pn_image_get_image_buffer ()

PnColor*    pn_image_get_image_buffer       (PnImage *image);

Retrieves the image buffer (the 'front buffer') of a PnImage.

image : a PnImage
Returns : A pointer to the image buffer


pn_image_get_transform_buffer ()

PnColor*    pn_image_get_transform_buffer   (PnImage *image);

Retrieves the transform buffer (the 'back buffer') of a PnImage. The transform buffer should only be used internally by transform actuators. *EVERY* pixel in the transform buffer *MUST* be set. The transform buffer can be 'copied' to the image buffer using pn_image_apply_transform().

image : a PnImage
Returns : A pointer to the transform buffer


pn_image_render_pixel ()

void        pn_image_render_pixel           (PnImage *image,
                                             guint x,
                                             guint y,
                                             PnColor color);

Renders a pixel to the image buffer of a PnImage. pn_image_set_render_mode() can be used to set the blend mode that is used by this function.

image : a PnImage
x : the x coordinate (left being 0)
y : the y coordinate (top being 0)
color : the color


pn_image_render_pixel_by_offset ()

void        pn_image_render_pixel_by_offset (PnImage *image,
                                             guint offset,
                                             PnColor color);

Renders a pixel to the image buffer of a PnImage based on a pixel offset rather than rectangular coordinates. This function should be used if there is a more optimum way to calculate the offset than multiplying at every pixel. pn_image_set_render_mode() can be used to set the blend mode that is used by this function.

image : a PnImage
offset : the pixel offset (0 being the top left) NOTE: Use (pitch>>2) rather than width
color : the color


pn_image_render_line ()

void        pn_image_render_line            (PnImage *image,
                                             guint x0,
                                             guint y0,
                                             guint x1,
                                             guint y1,
                                             PnColor color);

Renders a line from (x0,y0) to (x1,y1) to the image buffer of a PnImage. Currently ***NO CLIPPING IS CURRENTLY DONE!!!***

image : a PnImage
x0 : the x coordinate of the first point
y0 : the y coordinate of the first point
x1 : the x coordinate of the second point
y1 : the y coordinate of the second point
color : the color


pn_image_apply_transform ()

void        pn_image_apply_transform        (PnImage *image);

Renders the transform buffer onto the image buffer. pn_image_set_transform_mode() may be used to set the blend mode that is used by this function.

image : a PnImage


pn_image_render_image ()

void        pn_image_render_image           (PnImage *image,
                                             PnImage *src,
                                             PnBlendMode blend_mode);

Renders the image buffer of src onto the image buffer of an image.

image : a PnImage
src : the source image
blend_mode : the blend mode to use