The "viewimg" Package
These routines are meant to provide a high level mechanism to create and
manipulate viewable images (2-dimensional slices of Karma data structures).
These viewable images utilise the world canvases available in the
canvas package, hence the resulting code is device independent.
Library: karmagraphics
Link With: -lkarmagraphics
Functions
Prototype Functions
Tables
Functions
flag
viewimg_draw_edit_list (ViewableImage vimage, KImageEditList ilist)
This routine will draw a list of edit objects to the
2-dimensional data associated with a viewable image object.
Parameters:
- vimage :
The viewable image.
- ilist :
The list of edit objects.
Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe
flag
viewimg_draw_edit_object (ViewableImage vimage, char *object)
This routine will draw one edit object to the 2-dimensional data
associated with a viewable image object.
Parameters:
- vimage :
The viewable image.
- object :
The edit object.
Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe
void
viewimg_init (KWorldCanvas canvas)
This routine will initialise the viewimg package for a
particular world canvas. Calling this routine causes a number of callback
routines internal to the package to be registered with the canvas (such
as refresh and position event callbacks). The use of this routine is
optional at the moment: the routines which create viewable images perform
this function automatically. In version 2.0 of Karma, this use of this
routine before creating viewable images will become mandatory.
Parameters:
- canvas :
The world canvas object.
Returns: Nothing.
Multithreading Level: Unsafe
ViewableImage
viewimg_create_restr (KWorldCanvas canvas,
multi_array *multi_desc,
array_desc *arr_desc, char *slice,
unsigned int hdim, unsigned int vdim,
unsigned int elem_index,
unsigned num_restr,
char **restr_names, double *restr_values)
This routine will create a PseudoColour viewable image object
from a 2-dimensional slice of a Karma data structure. At a later time, this
viewable image may be made visible. This routine will not cause the canvas
to be refreshed.
Parameters:
- canvas :
The world canvas onto which the viewable image may be drawn. Many
viewable images may be associated with a single canvas.
- multi_desc :
The multi_array descriptor which contains the Karma data
structure. The routine increments the attachment count on the descriptor
on successful completion. This may be NULL.
- arr_desc :
The array descriptor.
- slice :
The start of the slice data.
- hdim :
The dimension index of the horizontal dimension.
- vdim :
The dimension index of the vertical dimension.
- elem_index :
The element index in the data packets.
- num_restr :
The number of matched restrictions. If this is 0, no
restrictions are recorded (this is the same as calling viewimg_create).
- restr_names :
The restriction names.
- restr_values :
The restriction values.
Returns: A viewable image on success, NULL.
Multithreading Level: Unsafe
Note: - Restriction information is automatically deallocated when
viewimg_destroy is called.
- The routine may produce cache data which will vastly increase the
speed of subsequent operations on this data. Prior to process exit, a call
MUST be made to viewimg_destroy, otherwise shared memory segments could
remain after the process exits.
ViewableImage
viewimg_create (KWorldCanvas canvas, multi_array *multi_desc,
array_desc *arr_desc, char *slice,
unsigned int hdim, unsigned int vdim,
unsigned int elem_index)
This routine will create a PseudoColour viewable image object
from a 2-dimensional slice of a Karma data structure. At a later time, this
viewable image may be made visible. This routine will not cause the canvas
to be refreshed.
Parameters:
- canvas :
The world canvas onto which the viewable image may be drawn. Many
viewable images may be associated with a single canvas.
- multi_desc :
The multi_array descriptor which contains the Karma data
structure. The routine increments the attachment count on the descriptor
on successful completion. This may be NULL.
- arr_desc :
The array descriptor.
- slice :
The start of the slice data.
- hdim :
The dimension index of the horizontal dimension.
- vdim :
The dimension index of the vertical dimension.
- elem_index :
The element index in the data packets.
Returns: A viewable image on success, NULL.
Multithreading Level: Unsafe
Note: - The routine may produce cache data which will vastly increase the
speed of subsequent operations on this data. Prior to process exit, a call
MUST be made to viewimg_destroy, otherwise shared memory segments could
remain after the process exits.
ViewableImage
viewimg_create_from_iarray (KWorldCanvas canvas, iarray array,
flag swap)
This routine will create a viewable image object from a
2-dimensional Intelligant Array. At a later time, this viewable image may
be made visible. This routine will not cause the canvas to be refreshed.
Many viewable images may be associated with a single canvas.
Parameters:
- canvas :
The world canvas object.
- array :
The Intelligent Array. The underlying multi_array data
structure will have its attachment count incremented upon successful
completion.
- swap :
If TRUE the y axis will be displayed horizontally.
Returns: A viewable image on success, else NULL.
Multithreading Level: Unsafe
Note: - The routine may produce cache data which will vastly increase the
speed of subsequent operations on this data. Prior to process exit, a call
MUST be made to viewimg_destroy, otherwise shared memory segments could
remain after the process exits.
ViewableImage *
viewimg_create_sequence (KWorldCanvas canvas,
multi_array *multi_desc,
array_desc *arr_desc, char *cube,
unsigned int hdim, unsigned int vdim,
unsigned int fdim,
unsigned int elem_index)
This routine will create a sequence of viewable image objects
from a 3-dimensional cube of a Karma data structure. At a later time, this
sequence of viewable images may be made visible in any order.
This routine will not cause the canvas to be refreshed.
Parameters:
- canvas :
The world canvas object.
- multi_desc :
The multi_array descriptor which contains the Karma data
structure. The routine increments the attachment count on the descriptor
on successful completion. This may be NULL.
- arr_desc :
The array descriptor.
- cube :
The start of the cube data.
- hdim :
The dimension index of the horizontal dimension.
- vdim :
The dimension index of the vertical dimension.
- fdim :
The dimension index of the frame dimension (dimension containing the
sequence). The number of frames is the same as the length of this
dimension.
- elem_index :
The element index in the data packets.
Returns: A pointer to a dynamically allocated array of viewable image
objects on success, else NULL.
Multithreading Level: Unsafe
Note: - The routine may produce cache data which will vastly increase the
speed of subsequent operations on this data. Prior to process exit, a call
MUST be made to viewimg_destroy, otherwise shared memory segments could
remain after the process exits.
ViewableImage
viewimg_create_rgb (KWorldCanvas canvas, multi_array *multi_desc,
array_desc *arr_desc, char *slice,
unsigned int hdim, unsigned int vdim,
unsigned int red_index,
unsigned int green_index,
unsigned int blue_index, unsigned num_restr,
char **restr_names, double *restr_values)
This routine will create a TrueColour viewable image object from
a 2-dimensional slice of a Karma data structure. At a later time, this
viewable image may be made visible. This routine will not cause the canvas
to be refreshed.
Parameters:
- canvas :
The world canvas onto which the viewable image may be drawn. Many
viewable images may be associated with a single canvas.
- multi_desc :
The multi_array descriptor which contains the Karma data
structure. The routine increments the attachment count on the descriptor on
successful completion. This may be NULL.
- arr_desc :
The array descriptor.
- slice :
The start of the slice data.
- hdim :
The dimension index of the horizontal dimension.
- vdim :
The dimension index of the vertical dimension.
- red_index :
The element index of the red component in the data packets.
- green_index :
The element index of the green component in the data packets.
- blue_index :
The element index of the blue component in the data packets.
- num_restr :
The number of matched restrictions. If this is 0, no
restrictions are recorded.
- restr_names :
The restriction names.
- restr_values :
The restriction values.
Returns: A viewable image on success, else NULL.
Multithreading Level: Unsafe
Note: - The 3 colour components must be of type K_UBYTE .
- Restriction information is automatically deallocated when
viewimg_destroy is called.
- The routine may produce cache data which will vastly increase the
speed of subsequent operations on this data. Prior to process exit, a call
MUST be made to viewimg_destroy, otherwise shared memory segments could
remain after the process exits.
ViewableImage *
viewimg_create_rgb_sequence (KWorldCanvas canvas,
multi_array *multi_desc,
array_desc *arr_desc, char *cube,
unsigned int hdim,
unsigned int vdim,
unsigned int fdim,
unsigned int red_index,
unsigned int green_index,
unsigned int blue_index,
unsigned num_restr,
char **restr_names,
double *restr_values)
This routine will create a sequence of TrueColour viewable image
objects from a 3-dimensional cube of a Karma data structure. At a later
time, this sequence of viewable images may be made visible in any order.
This routine will not cause the canvas to be refreshed.
Parameters:
- canvas :
The world canvas onto which the viewable image may be drawn. Many
viewable images may be associated with a single canvas.
- multi_desc :
The multi_array descriptor which contains the Karma data
structure must. The routine increments the attachment count on the
descriptor on successful completion. This may be NULL.
- arr_desc :
The array descriptor.
- cube :
The start of the cube data.
- hdim :
The dimension index of the horizontal dimension.
- vdim :
The dimension index of the vertical dimension.
- fdim :
The dimension index of the frame dimension (dimension containing the
sequence). The number of frames is the same as the length of this dimension
- red_index :
The element index of the red component in the data packets.
- green_index :
The element index of the green component in the data packets.
- blue_index :
The element index of the blue component in the data packets.
- num_restr :
The number of matched restrictions. If this is 0, no
restrictions are recorded.
- restr_names :
The restriction names.
- restr_values :
The restriction values.
Returns: A viewable image on success, else NULL.
Multithreading Level: Unsafe
Note: - The 3 colour components must be of type K_UBYTE.
- Restriction information is copied into internally allocated
storage.
- The routine may produce cache data which will vastly increase the
speed of subsequent operations on this data. Prior to process exit, a call
MUST be made to viewimg_destroy, otherwise shared memory segments could
remain after the process exits.
flag
viewimg_make_active (ViewableImage vimage)
This routine will make a viewable image the active image for its
associated world canvas. The canvas is then refreshed (possibly resized),
provided that the new viewable image was not already active.
Parameters:
- vimage :
The viewable image.
Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe
See Also: ALSO] viewimg_set_active.
flag
viewimg_set_active (ViewableImage vimage, flag refresh)
This routine will make a viewable image the active image for its
associated world canvas.
Parameters:
- vimage :
The viewable image.
- refresh :
If TRUE, the canvas is always refreshed, if FALSE, the canvas is
not refreshed.
Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe
See Also: ALSO] viewimg_make_active.
flag
viewimg_register_data_change (ViewableImage vimage)
This routine will register a change in the Karma data structure
associated with a viewable image. If the viewable image is active, it will
be immediately redrawn on its canvas.
Parameters:
- vimage :
The viewable image.
Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe
void
viewimg_destroy (ViewableImage vimage)
This routine will destroy a viewable image. If this is not called
prior to process exit, shared memory segments could remain after the
process exits.
Parameters:
- vimage :
The viewable image.
Returns: Nothing.
Multithreading Level: Unsafe
Note: - The associated multi_array descriptor is also deallocated (or
at least, the attachment count is decreased).
ViewableImage
viewimg_get_active (KWorldCanvas canvas)
Get the active ViewableImage associated with a world canvas.
Parameters:
- canvas :
The world canvas object.
Returns: The active viewable image on success, else NULL (indicating no
viewable image is active for the canvas).
Multithreading Level: Unsafe
flag
viewimg_test_active (ViewableImage vimage)
This routine will test if a viewable image is the active image
for its associated world canvas.
Parameters:
- vimage :
The viewable image.
Returns: TRUE if the viewable image is actice, else FALSE.
Multithreading Level: Unsafe
KCallbackFunc
viewimg_register_position_event_func (KWorldCanvas canvas,
flag (*func) (),
void *f_info)
This routine will register a position event function for a world
canvas which has a number of ViewableImage objects associated with it.
The position event function will be called whenever a position event on the
canvas has not been consumed. Many position event functions may be
registered per canvas. The first function registered is the first function
called upon a position event.
Parameters:
- canvas :
The world canvas object.
- func :
The function that is called when a position event occurs. The
prototype function is VIEWIMG_PROTO_position_func.
- f_info :
The initial arbitrary function information pointer.
Returns: A handle to a KWorldCanvasPositionFunc object.
Multithreading Level: Unsafe
flag
viewimg_fill_ellipse (ViewableImage vimage,
double centre_x, double centre_y,
double radius_x, double radius_y, double value[2])
This routine will draw a filled ellipse into a 2 dimensional
slice of data associated with a viewable image.
Parameters:
- vimage :
The viewable image.
- centre_x :
The horizontal world co-ordinate of the centre of the ellipse.
- centre_y :
The vertical world co-ordinate of the centre of the ellipse.
- radius_x :
The horizontal radius.
- radius_y :
The vertical radius.
- value :
The complex value to fill the ellipse. This must be of type
K_DCOMPLEX.
Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe
flag
viewimg_fill_polygon (ViewableImage vimage, edit_coord *coords,
unsigned int num_vertices, double value[2])
This routine will draw a filled polygon into a 2 dimensional
slice of data associated with a viewable image.
Parameters:
- vimage :
The viewable image.
- coords :
The array of world co-ordinates of vertices of the polygon.
- num_vertices :
The number of vertices in the polygon.
- value :
The complex value to fill the polygon with. This must be of type
K_DCOMPLEX.
Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe
void
viewimg_get_canvas_attributes (KWorldCanvas canvas, ...)
Get the viewable image attributes for a world canvas.
Parameters:
- canvas :
The world canvas object.
- ... :
The list of parameter attribute-key attribute-value-ptr pairs
must follow. This list must be terminated with the VIEWIMG_ATT_END.
See VIEWIMG_CANVAS_ATTRIBUTES for the list of attributes.
Returns: Nothing.
Multithreading Level: Unsafe
void
viewimg_set_canvas_attributes (KWorldCanvas canvas, ...)
This routine will control the autoscaling options used when
viewable images are displayed on their associated world canvas.
Parameters:
- canvas :
The world canvas.
- ... :
The list of parameter attribute-key attribute-value-ptr pairs
must follow. This list must be terminated with the VIEWIMG_ATT_END.
See VIEWIMG_CANVAS_ATTRIBUTES for the list of attributes.
Returns: Nothing.
Multithreading Level: Unsafe
Note: - The canvas is not refreshed by this operation.
void
viewimg_get_attributes (ViewableImage vimage, ...)
Get the attributes for a viewable image.
Parameters:
- vimage :
The ViewableImage.
- ... :
The list of parameter attribute-key attribute-value-ptr pairs
must follow. This list must be terminated with the VIEWIMG_VATT_END. See
VIEWIMG_VIMAGE_ATTRIBUTES for the list of attributes.
Returns: Nothing.
Multithreading Level: Unsafe
KWorldCanvas
viewimg_get_worldcanvas (ViewableImage vimage)
Get the world canvas for a viewable image.
Parameters:
- vimage :
The ViewableImage object.
Returns: The KWorldCanvas object.
Multithreading Level: Unsafe
Prototype Functions
flag
VIEWIMG_PROTO_position_func (ViewableImage vimage, double x, double y,
void *value, unsigned int event_code,
void *e_info, void **f_info,
double x_lin, double y_lin,
unsigned int value_type)
This routine is a position event consumer for a world canvas
which has a number of ViewableImage objects associated with it.
Parameters:
- viewimg :
The active viewable image.
- x :
The horizontal world co-ordinate of the event.
- y :
The vertical world co-ordinate of the event.
These values will have been transformed by the registered transform
function (see canvas_register_transform_func) for the associated
world canvas.
- value :
A pointer to the data value in the viewable image corresponding
to the event co-ordinates.
- event_code :
The arbitrary event code.
- e_info :
The arbitrary event information.
- f_info :
The arbitrary function information pointer.
- x_lin :
The linear horizontal world co-ordinate (the co-ordinate prior
to the transform function being called).
- y_lin :
The linear vertical world co-ordinate (the co-ordinate prior
to the transform function being called).
- value_type :
The type of the data value. This may be K_DCOMPLEX or
K_UB_RGB.
Returns: TRUE if the event was consumed, else FALSE indicating that
the event is still to be processed.
Multithreading Level: Unsafe
Tables
VIEWIMG_CANVAS_ATTRIBUTES
| Name | Get Type | Set Type | Meaning
|
|
|
| VIEWIMG_ATT_END | | | End of varargs list
|
| VIEWIMG_ATT_AUTO_X | flag * | flag | Enable automatic horizontal scaling
|
| VIEWIMG_ATT_AUTO_Y | flag * | flag | Enable automatic vertical scaling
|
| VIEWIMG_ATT_AUTO_V | flag * | flag | Enable automatic intensity scaling
|
| VIEWIMG_ATT_INT_X | flag * | flag | Force integer horizontal zoom-in/zoom-out factor
|
| VIEWIMG_ATT_INT_Y | flag * | flag | Force integer vertical zoom-in/zoom-out factor
|
| VIEWIMG_ATT_MAINTAIN_ASPECT | flag * | flag | Maintain data image aspect ratio
|
| VIEWIMG_ATT_ALLOW_TRUNCATION | flag * | flag | Allow shrunken images to be truncated.
|
VIEWIMG_VIEWIMG_ATTRIBUTES
| Name | Get Type | Set Type | Meaning
|
|
|
| VIEWIMG_VATT_END | | | End of varargs list
|
| VIEWIMG_VATT_TRUECOLOUR | flag * | flag | Image is TrueColour
|
| VIEWIMG_VATT_ARRAY_DESC | array_desc ** | array_desc * | The array descriptor for the image
|
| VIEWIMG_VATT_SLICE | char ** | char * | Start of the image data
|
| VIEWIMG_VATT_HDIM | unsigned int * | unsigned int | The horizontal dimension
|
| VIEWIMG_VATT_VDIM | unsigned int * | unsigned int | The vertical dimension
|
| VIEWIMG_VATT_PSEUDO_INDEX | unsigned int * | unsigned int | The PseudoColour element index
|
| VIEWIMG_VATT_RED_INDEX | unsigned int * | unsigned int | The TrueColour red element index
|
| VIEWIMG_VATT_GREEN_INDEX | unsigned int * | unsigned int | The TrueColour green element index
|
| VIEWIMG_VATT_BLUE_INDEX | unsigned int * | unsigned int | The TrueColour blue element index
|
Contact: Richard Gooch
Web Development: Ariel Internet Services