root/paper-tape-project/trunk/visualisator/lochstreifen.h

#ifndef __LOCHSTREIFEN_H__
#define __LOCHSTREIFEN_H__

// if C++ compiling...
#ifdef __cplusplus
extern "C" {
#endif 

#include <cairo-svg.h> /* because using cairo_t */

typedef unsigned char byte_t;
typedef struct lochstreifen LOCHSTREIFEN;

/**
 * Identifing a track.
 * This enum is used in various functions.
 * Principally it's only sensefule for the
 * LOCHSTREIFEN_NO_TRACK value.
 **/
typedef enum lochstreifen_track {
        LOCHSTREIFEN_TRACK_0        = 0,
        LOCHSTREIFEN_TRACK_1        = 1,
        LOCHSTREIFEN_TRACK_2        = 2,
        LOCHSTREIFEN_TRACK_FEED     = -13,
        LOCHSTREIFEN_TRACK_3        = 3,
        LOCHSTREIFEN_TRACK_4        = 4,
        LOCHSTREIFEN_TRACK_5        = 5,
        LOCHSTREIFEN_TRACK_6        = 6,
        LOCHSTREIFEN_TRACK_7        = 7,
        LOCHSTREIFEN_NO_TRACK       = -42
} track_t;

/**
 * This typedef just says: This int represents a row in a LOCHSTREIFEN
 * It's range should be >= 0 and <= the data_len member of the
 * LOCHSTREIFEN structure.
 * The MAX_INT value is therefore also the value of bytes which can be
 * drawn: 4 GB. That's pretty much, because it all must be held in RAM ;-)
 **/
typedef int row_t;

/**
 * The adequate to the lochstreifen_track enum value LOCHSTREIFEN_NO_TRACK.
 * If a row_t == LOCHSTREIFEN_NO_ROW, it indicates that this
 * is not a row at all. Of course you could also simply use check if
 * row_t is < 0, but this is more meaningful.
 **/
#define LOCHSTREIFEN_NO_ROW  -1

/**
 * To be used as a return value, in comparision with
 * LOCHSTREIFEN_NO_ROW and LOCHSTREIFEN_NO_TRACK: It indicates that
 * everything successed.
 **/
#define LOCHSTREIFEN_SUCCESS (-42*42)

/**
 * This is the LOCHSTREIFEN structure. It will always be referenced as a
 * pointer, created by lochstreifen_new(). This function will also
 * initialize the LOCHSTREIFEN structure.
 * It's commonly referenced as "*l" or "l->", using "l" as abbrevation
 * for LOCHSTREIFEN.
 **/
struct lochstreifen {
        /* DATA (not supposed to be set directly) */
        /// Length of data array (counting from 1, like argc)
        int data_length;
        /// data array (the data which LOCHSTREIFEN will print)
        byte_t *data;

        /* COLORS / SWITCHES WHETER PARTS ARE PAINTED */
        cairo_pattern_t *outer_background_color;
        cairo_pattern_t *papertape_background_color;
        cairo_pattern_t *one_code_hole_color;
        cairo_pattern_t *zero_code_hole_color;
        cairo_pattern_t *feed_hole_color;

        /// Highlighting a (row/byte) region
        row_t highlight_region_start; ///< counting from 0, already in selection
        row_t highlight_region_end;   ///< counting from 0, no more in selection
        cairo_pattern_t *highlight_region_color; ///< == NULL => no selection painted

        /// Highlight one special row
        row_t highlight_row_number;  ///< counting from 0
        cairo_pattern_t *highlight_row_color;

        /// Highlight one special bit (not complete track)
        row_t   highlight_bit_row;
        track_t highlight_bit_track;
        cairo_pattern_t *highlight_bit_color;

        /// Perfomant Clipping
        cairo_rectangle_t *clip;
        
        /// Matrix to apply for every paint process
        /// Call lochstreifen_check_matrix() after you have touched it.
        cairo_matrix_t matrix;

        /// Callback functions:
        void (*row_callback) (const row_t* current_row, cairo_t* context, void* user_data);
        void* row_callback_user_data;
        //void (*bit_callback)
        // etc.

        /*<private>*/
        /* The following datas are private. */
        
        /// Make debug output if debug != 0.
        byte_t debug;
        
        /// Inverse CTM. Don't touch it, use
        /// lochstreifen_check_matrix() instead to calculate it automatically
        cairo_matrix_t matrix_inverse;
};

/// The default color values
#define LOCHSTREIFEN_DEFAULT_OUTER_BACKGROUND_COLOR        NULL
#define LOCHSTREIFEN_DEFAULT_PAPERTAPE_BACKGROUND_COLOR    cairo_pattern_create_rgb(0.7, 0.7, 0.7)
#define LOCHSTREIFEN_DEFAULT_ONE_CODE_HOLE_COLOR           cairo_pattern_create_rgb(0,   0,   0)
#define LOCHSTREIFEN_DEFAULT_ZERO_CODE_HOLE_COLOR          NULL
#define LOCHSTREIFEN_DEFAULT_FEED_HOLE_COLOR               cairo_pattern_create_rgb(0.5, 0.7, 1)
#define LOCHSTREIFEN_DEFAULT_HIGHLIGHT_REGION_COLOR        cairo_pattern_create_rgb(0.95,  1, 0)
#define LOCHSTREIFEN_DEFAULT_HIGHLIGHT_ROW_COLOR           cairo_pattern_create_rgb(1,     0, 0)
#define LOCHSTREIFEN_DEFAULT_HIGHLIGHT_BIT_COLOR           cairo_pattern_create_rgb(1,1,1)
#define LOCHSTREIFEN_DEFAULT_CTM                           { 1, 0, 0, 1, 0, 0 }

/// dimensions of the paper tape after ECMA-10 standard

// width of paper tape, according to "PROPERTIES OF UNPUNCHED TAPE", section 1.1.2:
// 25.40mm = 1". This is the "base" unit in our vector drawing.
#define LOCHSTREIFEN_WIDTH                 1.0

// length of tear-off: about the half of the width of a papertape
#define LOCHSTREIFEN_TEAR_OFF_LENGTH       ( 0.5 * LOCHSTREIFEN_WIDTH )

// Within a row the distance of the centres of the code holes from
// the centre of the feed hole shall be 2,54mm (=0.1"), where n is an integer.
#define LOCHSTREIFEN_TRACK_DISTANCE        0.1

// The distance between two adjacent rows shall be 2,54mm (=0.1") measured
// at the feed holes.
#define LOCHSTREIFEN_ROW_DISTANCE          0.1

// feed hole diameter: 1.170mm
#define LOCHSTREIFEN_RADIUS_FEED_HOLE    ( (1.170 / 25.40) / 2)

// code hol diameter: 1.83mm
#define LOCHSTREIFEN_RADIUS_CODE_HOLE    ( (1.830 / 25.40) / 2)

// length of paper tape: Tear off at start and end, data rows + 0.05" offset at start + end spacing
#define LOCHSTREIFEN_LENGTH              ( 2 * LOCHSTREIFEN_TEAR_OFF_LENGTH + \
                                           LOCHSTREIFEN_ROW_DISTANCE * (l->data_length + 1) )

typedef enum lochstreifen_direction {
        // special values for compatibility to old implementation
        LOCHSTREIFEN_MOVEMENT_TO_LEFT       = 0,
        LOCHSTREIFEN_MOVEMENT_TO_TOP        = 1,
        LOCHSTREIFEN_MOVEMENT_TO_RIGHT      = 2,
        LOCHSTREIFEN_MOVEMENT_TO_BOTTOM     = 3,
        LOCHSTREIFEN_MOVEMENT_NONE          = -1,
        LOCHSTREIFEN_ROTATION_CLOCKWISE     = 4,
        LOCHSTREIFEN_ROTATION_ANTICLOCKWISE = 5
} lochstreifen_direction_t;





// functions
LOCHSTREIFEN *lochstreifen_new();
LOCHSTREIFEN* lochstreifen_copy(const LOCHSTREIFEN* t);
void lochstreifen_free(LOCHSTREIFEN* l);
void lochstreifen_print_debug(LOCHSTREIFEN* l);
void lochstreifen_set_data(LOCHSTREIFEN *l, int data_length, byte_t *data);
void lochstreifen_add_null_bytes(LOCHSTREIFEN *l, int start, int end);
double lochstreifen_get_length(LOCHSTREIFEN *l);
void lochstreifen_set_highlight_region(LOCHSTREIFEN *l, int start, int end);
int lochstreifen_get_highlight_region(LOCHSTREIFEN *l, int *start, int *end);
void lochstreifen_remove_highlight_region(LOCHSTREIFEN *l);
void lochstreifen_set_highlight_row(LOCHSTREIFEN *l, int number_of_row);
int lochstreifen_get_highlight_row(LOCHSTREIFEN *l);
void lochstreifen_remove_highlight_row(LOCHSTREIFEN *l);
void lochstreifen_set_highlight_bit(LOCHSTREIFEN *l, int number_of_row, int number_of_bit);
int lochstreifen_get_highlight_bit(LOCHSTREIFEN *l, int *number_of_row, int *number_of_bit);
void lochstreifen_remove_highlight_bit(LOCHSTREIFEN *l);
void lochstreifen_set_clip(LOCHSTREIFEN *l, double x, double y, double width, double height);
void lochstreifen_remove_clip(LOCHSTREIFEN *l);
void lochstreifen_check_matrix(LOCHSTREIFEN* l);
void lochstreifen_set_scaling_by_length(LOCHSTREIFEN *l, int length);
void lochstreifen_set_scaling_by_width(LOCHSTREIFEN *l, int width);
void lochstreifen_set_scaling_by_code_hole(LOCHSTREIFEN *l, int diameter);
void lochstreifen_get_target_dimensions(LOCHSTREIFEN *l, int *width, int *height);
int lochstreifen_get_target_width(LOCHSTREIFEN *l);
int lochstreifen_get_target_height(LOCHSTREIFEN *l);
void lochstreifen_get_target_bit_from_point(LOCHSTREIFEN* l, row_t* row, track_t* track, double x, double y);
row_t lochstreifen_get_target_row_from_point(LOCHSTREIFEN* l, double x, double y);
track_t lochstreifen_get_target_track_from_point(LOCHSTREIFEN* l, double x, double y);
int lochstreifen_get_target_rect_from_row(LOCHSTREIFEN* l, row_t row, cairo_rectangle_t* rect);
int lochstreifen_get_target_rect_from_bit(LOCHSTREIFEN* l, row_t row, track_t track, cairo_rectangle_t* rect);
void lochstreifen_set_rotation(LOCHSTREIFEN *l, enum lochstreifen_direction direction);
void lochstreifen_draw(LOCHSTREIFEN *l, cairo_t *cr);

#ifdef __cplusplus
} // extern "C"
#endif 


#endif /* __LOCHSTREIFEN_H__ */