Image Data

Name

Image Data -- Data Representing Hexagonal Images

Synopsis


#include <hexmap.h>



struct      HexData;


HexData*    hex_data_new                    (gpointer data,
                                             guint width,
                                             HexDrawFunc draw_func,
                                             GDestroyNotify destroy_func);

void        (*HexDrawFunc)                  (void);
typedef     HexColor;

HexData*    hex_data_new_from_xpm_d         (const gchar **xpm_d);
HexData*    hex_data_new_from_color         (HexColor *color,
                                             guint width);
HexData*    hex_data_new_border             (HexColor *color,
                                             HexDirection dir,
                                             guint width);
HexData*    hex_data_new_from_file          (const gchar *filename,
                                             GError **err);
HexData*    hex_data_new_empty_cached       (guint width);

void        hex_data_ref                    (HexData *data);
void        hex_data_unref                  (HexData *data);

Description

The HexData structure is used to hold image data. Other routines in the library cache what is drawn by HexData, using its address as a refernce. Therefore, once a HexData has been created, its drawing operation should always produce the same result (when applied to the same underlying image). Basically, there are three permissible operations on a HexData:

1. Ref and unref

2. Draw

3. Get its width (read only)

A HexData is treated by the library as low level image data, functioning somewhat like a GdkPixmap. The differences are primarily due to the fact that it uses a drawing function, instead of an image which is directly displayed.

Details

struct HexData

struct HexData {
  guint             ref_count;
  guint             width;
  gpointer          data;
  HexDrawFunc       draw_func;
  GDestroyNotify    destroy_func;
};

A structure representing hexagonal image data. Its only attribute is its width, since all other dimensions of the hex can be calculated from this.


hex_data_new ()

HexData*    hex_data_new                    (gpointer data,
                                             guint width,
                                             HexDrawFunc draw_func,
                                             GDestroyNotify destroy_func);

create a new HexData

data :

Data to be used by draw_func

width :

The width of the hex in pixels. The height of the hex is given by HEX_HEIGHT().

draw_func :

A function which draws the hex. The image drawn by a given HexData should never change, as this messes up internal caching. It can be NULL, in which case the HexData represents a blank hex with a definite width

destroy_func :

A function to free data when the HexData is destroyed.

Returns :

a newly created HexData object


HexDrawFunc ()

void        (*HexDrawFunc)                  (void);

The prototype for the draw function passed to hex_data_new(). This is an abstract prototype, the real prototype definition is HexDrawFuncFoo in the backend headers.


HexColor

An RGB color


hex_data_new_from_xpm_d ()

HexData*    hex_data_new_from_xpm_d         (const gchar **xpm_d);

create a new HexData from xpm data

xpm_d :

The data for the xpm, in the usual format. This must have the aspect ratio given by HEX_HEIGHT().

Returns :

a newly created HexData


hex_data_new_from_color ()

HexData*    hex_data_new_from_color         (HexColor *color,
                                             guint width);

create a new HexData which is a solid color

color :

a HexColor

width :

The width of the hex. The height is given by HEX_HEIGHT().

Returns :

a newly created HexData


hex_data_new_border ()

HexData*    hex_data_new_border             (HexColor *color,
                                             HexDirection dir,
                                             guint width);

create a new HexData which is a colored border

color :

A HexColor

dir :

A HexDirection indicating which sides of the border to draw. Use HEX_DIRECTION_MASK to draw all sides.

width :

The width of the hex. The height is given by HEX_HEIGHT().

Returns :

a newly created HexData


hex_data_new_from_file ()

HexData*    hex_data_new_from_file          (const gchar *filename,
                                             GError **err);

create a new HexData from a file

filename :

A file containing the data. This must have the aspect ratio given by HEX_HEIGHT().

err :

A location to return errors generated while loading the file.

Returns :

a newly created HexData. If the file does not have the correct aspect ratio, or if an error occurs, returns NULL.


hex_data_new_empty_cached ()

HexData*    hex_data_new_empty_cached       (guint width);

Get a cached blank HexData. If width is 0, the cache is flushed and NULL is returned.

A non-cached blank HexData may be obtained by calling hex_data_new() with NULL for every argument except the width.

width :

The width of the hex. The height is given by HEX_HEIGHT().

Returns :

a newly created HexData


hex_data_ref ()

void        hex_data_ref                    (HexData *data);

Increments the reference count on a HexData.

data :

A HexData


hex_data_unref ()

void        hex_data_unref                  (HexData *data);

Decrements the reference count on a HexData, and frees it if the count falls to zero.

data :

A HexData