# The "psw" Package

These routines provide PostScript generation facilities.

Library: karma
Link With: -lkarma

#### Functions

psw_va_create | Create a PostScriptPage object.
psw_mono_image | Write a monochrome image to a PostScriptPage object.
psw_pseudocolour_image | Write a pseudocolour image to a PostScriptPage object.
psw_rgb_image | Write a truecolour image to a PostScriptPage object.
psw_directcolour_image | Write a directcolour image to a PostScriptPage object.
psw_close | Close a PostScriptPage object.
psw_rgb_line | Write a colour line to a PostScriptPage object.
psw_rgb_polygon | Write a colour polygon to a PostScriptPage object.
psw_rgb_arc | Write a colour arc to a PostScriptPage object.
psw_rgb_ellipse | Write a colour ellipse to a PostScriptPage object.
psw_rgb_text | Write a colour string to a PostScriptPage object.
psw_set_attributes | Set the attributes for a PostScriptPage object.
psw_get_media_size | Get size of a known media type.
psw_set_clip_areas | Set the clip areas.

#### Tables

psw_ATTRIBUTES | List of attributes for PostScriptPage object
psw_TRAY_TYPES | List of PostScript tray types

## Functions

PostScriptPage psw_va_create (Channel channel, double hoffset, double voffset, double hsize, double vsize, flag portrait, flag eps, ...)

This routine will create a PostScriptPage object ready for writing PostScript commands to. The routine automatically writes the PostScript header.

Parameters:

- channel : The channel to write to.
- hoffset : The horizontal offset (in centimeters) of the co-ordinate origin.
- voffset : The vertical offset (in centimeters) of the co-ordinate origin.
- hsize : The desired horizontal size of the co-ordinate system (in centimeters).
- vsize : The desired vertical size of the co-ordinate system (in centimeters).
- portrait : If TRUE, objects will be drawn in portrait mode (i.e. the x-axis will be horizontal), else they will be drawn in landscape mode (i.e. the x-axis will be vertical).
- eps : If TRUE the file format will be Encapsulated PostScript, else regular PostScript is written.
- ... : The optional list of parameter attribute-key attribute-value pairs must follow. This list must be terminated with the value PSW_ATT_END. See psw_ATTRIBUTES for a list of defined attributes.

Returns: A PostScriptPage object on success, else NULL
Multithreading Level: Unsafe
Note:

- All subsequent objects drawn must lie in the range (0.0, 0.0) to (1.0, 1.0)

flag psw_mono_image (PostScriptPage pspage, CONST unsigned char *image, unsigned int xlen, unsigned int ylen, CONST uaddr *xoffsets, CONST uaddr *yoffsets, CONST unsigned char imap[256], double xstart, double ystart, double xend, double yend)

Write a monochrome image to a PostScriptPage object.

Parameters:

- pspage : The PostScriptPage object.
- image : The image.
- xlen : The horizontal size of the image (in pixels).
- ylen : The vertical size of the image (in pixels).
- xoffsets : The horizontal offset array. If this is NULL, the image data is assumed to be contiguous in memory.
- yoffsets : The vertical offset array. If this is NULL, the image data is assumed to be contiguous in memory.
- imap : The intensity mapping to use. If this is NULL, a linear mapping is used (0 = black, 255 = white).
- xstart : The x starting point (scaled from 0.0 to 1.0).
- ystart : The y starting point (scaled from 0.0 to 1.0).
- xend : The x ending point (scaled from 0.0 to 1.0).
- yend : The y ending point (scaled from 0.0 to 1.0).

Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe

flag psw_pseudocolour_image (PostScriptPage pspage, CONST unsigned char *image, unsigned int xlen, unsigned int ylen, CONST uaddr *xoffsets, CONST uaddr *yoffsets, CONST unsigned char imap_red[256], CONST unsigned char imap_green[256], CONST unsigned char imap_blue[256], double xstart, double ystart, double xend, double yend)

Write a pseudocolour image to a PostScriptPage object.

Parameters:

- pspage : The PostScriptPage object.
- image : The image.
- xlen : The horizontal size of the image (in pixels).
- ylen : The vertical size of the image (in pixels).
- xoffsets : The horizontal offset array. If this is NULL, the image data is assumed to be contiguous in memory.
- yoffsets : The vertical offset array. If this is NULL, the image data is assumed to be contiguous in memory.
- imap_red : The red component colourmap entries.
- imap_green : The green component colourmap entries.
- imap_blue : The blue component colourmap entries.
- xstart : The x starting point (scaled from 0.0 to 1.0).
- ystart : The y starting point (scaled from 0.0 to 1.0).
- xend : The x ending point (scaled from 0.0 to 1.0).
- yend : The y ending point (scaled from 0.0 to 1.0).

Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe

flag psw_rgb_image (PostScriptPage pspage, CONST unsigned char *image_reds, CONST unsigned char *image_greens, CONST unsigned char *image_blues, unsigned int xlen, unsigned int ylen, CONST uaddr *xoffsets_red, CONST uaddr *yoffsets_red, CONST uaddr *xoffsets_green, CONST uaddr *yoffsets_green, CONST uaddr *xoffsets_blue, CONST uaddr *yoffsets_blue, uaddr stride, double xstart, double ystart, double xend, double yend)

Write a truecolour image to a PostScriptPage object.

Parameters:

- pspage : The PostScriptPage object.
- image_red : The red component image.
- image_green : The green component image.
- image_blue : The blue component image.
- xlen : The horizontal size of the image (in pixels).
- ylen : The vertical size of the image (in pixels).
- xoffsets_red : The horizontal offset array for the red component image. If this is NULL, the image data is assumed to be contiguous in memory.
- yoffsets_red : The vertical offset array for the red component image. If this is NULL, the image data is assumed to be contiguous in memory.
- xoffsets_green : The horizontal offset array for the green component image. If this is NULL, the image data is assumed to be contiguous in memory.
- yoffsets_green : The vertical offset array for the green component image. If this is NULL, the image data is assumed to be contiguous in memory.
- xoffsets_blue : The horizontal offset array for the blue component image. If this is NULL, the image data is assumed to be contiguous in memory.
- yoffsets_blue : The vertical offset array for the blue component image. If this is NULL, the image data is assumed to be contiguous in memory.
- stride : The stride of successive component values. This is ignored if both offset arrays are supplied for a component image.
- xstart : The x starting point (scaled from 0.0 to 1.0).
- ystart : The y starting point (scaled from 0.0 to 1.0).
- xend : The x ending point (scaled from 0.0 to 1.0).
- yend : The y ending point (scaled from 0.0 to 1.0).

Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe

flag psw_directcolour_image (PostScriptPage pspage, CONST unsigned char *image_reds, CONST unsigned char *image_greens, CONST unsigned char *image_blues, unsigned int xlen, unsigned int ylen, CONST uaddr *xoffsets_red, CONST uaddr *yoffsets_red, CONST uaddr *xoffsets_green, CONST uaddr *yoffsets_green, CONST uaddr *xoffsets_blue, CONST uaddr *yoffsets_blue, uaddr stride, CONST unsigned char imap_red[256], CONST unsigned char imap_green[256], CONST unsigned char imap_blue[256], double xstart, double ystart, double xend, double yend)

Write a directcolour image to a PostScriptPage object.

Parameters:

- pspage : The PostScriptPage object.
- image_red : The red component image.
- image_green : The green component image.
- image_blue : The blue component image.
- xlen : The horizontal size of the image (in pixels).
- ylen : The vertical size of the image (in pixels).
- xoffsets_red : The horizontal offset array for the red component image. If this is NULL, the image data is assumed to be contiguous in memory.
- yoffsets_red : The vertical offset array for the red component image. If this is NULL, the image data is assumed to be contiguous in memory.
- xoffsets_green : The horizontal offset array for the green component image. If this is NULL, the image data is assumed to be contiguous in memory.
- yoffsets_green : The vertical offset array for the green component image. If this is NULL, the image data is assumed to be contiguous in memory.
- xoffsets_blue : The horizontal offset array for the blue component image. If this is NULL, the image data is assumed to be contiguous in memory.
- yoffsets_blue : The vertical offset array for the blue component image. If this is NULL, the image data is assumed to be contiguous in memory.
- stride : The stride of successive component values. This is ignored if both offset arrays are supplied for a component image.
- imap_red : The red component colourmap entries.
- imap_green : The green component colourmap entries.
- imap_blue : The blue component colourmap entries.
- xstart : The x starting point (scaled from 0.0 to 1.0).
- ystart : The y starting point (scaled from 0.0 to 1.0).
- xend : The x ending point (scaled from 0.0 to 1.0).
- yend : The y ending point (scaled from 0.0 to 1.0).

Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe

flag psw_close (PostScriptPage pspage, flag flush, flag close)

This routine will write a tail to a PostScriptPage object and will deallocate the object.

Parameters:

- pspage : The PostScriptPage object.
- flush : If TRUE, the underlying channel obect is flushed.
- close : If TRUE, the underlying channel obect is closed.

Returns: TRUE on succes, else FALSE. In either case, the PostScriptPage object is deallocated (and closed if close is TRUE).
Multithreading Level: Unsafe

flag psw_rgb_line (PostScriptPage pspage, double red, double green,double blue, double xstart, double ystart, double xend, double yend)

Write a colour line to a PostScriptPage object.

Parameters:

- pspage : The PostScriptPage object.
- red : The red component value. The range is: 0.0 (dark) to 1.0 (light)
- green : The green component value. The range is: 0.0 (dark) to 1.0 (light)
- blue : The blue component value. The range is: 0.0 (dark) to 1.0 (light)
- xstart : The x starting point (scaled from 0.0 to 1.0).
- ystart : The y starting point (scaled from 0.0 to 1.0).
- xend : The x ending point (scaled from 0.0 to 1.0).
- yend : The y ending point (scaled from 0.0 to 1.0).

Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe

flag psw_rgb_polygon (PostScriptPage pspage, double red, double green, double blue, CONST double *x_arr, CONST double *y_arr, unsigned int num_points, flag fill)

Write a colour polygon to a PostScriptPage object.

Parameters:

- pspage : The PostScriptPage object.
- red : The red component value. The range is: 0.0 (dark) to 1.0 (light)
- green : The green component value. The range is: 0.0 (dark) to 1.0 (light)
- blue : The blue component value. The range is: 0.0 (dark) to 1.0 (light)
- x_arr : The array of x vertices. This is scaled from 0.0 to 1.0
- y_arr : The array of y vertices. This is scaled from 0.0 to 1.0
- num_points : The number of vertices.
- fill : If TRUE, the polygon is filled.

Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

flag psw_rgb_arc (PostScriptPage pspage, double red, double green, double blue, double cx, double cy, double rx, double ry, double angle1, double angle2, double rotation, flag fill)

Write a colour arc to a PostScriptPage object.

Parameters:

- pspage : The PostScriptPage object.
- red : The red component value. The range is: 0.0 (dark) to 1.0 (light)
- green : The green component value. The range is: 0.0 (dark) to 1.0 (light)
- blue : The blue component value. The range is: 0.0 (dark) to 1.0 (light)
- cx : The x centre. This is scaled from 0.0 to 1.0
- cy : The y centre. This is scaled from 0.0 to 1.0
- rx : The x radius. This is scaled from 0.0 to 1.0
- ry : The y radius. This is scaled from 0.0 to 1.0
- angle1 : The start of the arc, in units of degrees, relative to +X. Increasing positive values are anticlockwise.
- angle2 : The end of the arc, in units of degrees, relative to +X. Increasing positive values are anticlockwise.
- rotation : The rotation of the arc, in degrees. A rotation of 0 degrees corresponds to (x > 0, y = 0). A rotation of 90 degrees corresponds to (x = 0, y > 0). In other words, the angle increases anticlockwise from the right.
- fill : If TRUE, the ellipse is filled.

Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe

flag psw_rgb_ellipse (PostScriptPage pspage, double red, double green, double blue, double cx, double cy, double rx, double ry, flag fill)

Write a colour ellipse to a PostScriptPage object.

Parameters:

- pspage : The PostScriptPage object.
- red : The red component value. The range is: 0.0 (dark) to 1.0 (light)
- green : The green component value. The range is: 0.0 (dark) to 1.0 (light)
- blue : The blue component value. The range is: 0.0 (dark) to 1.0 (light)
- cx : The x centre. This is scaled from 0.0 to 1.0
- cy : The y centre. This is scaled from 0.0 to 1.0
- rx : The x radius. This is scaled from 0.0 to 1.0. If this is 0.0, then half of the thin linewidth value is used instead.
- ry : The y radius. This is scaled from 0.0 to 1.0. If this is 0.0, then half of the thin linewidth value is used instead.
- fill : If TRUE, the ellipse is filled.

Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe

flag psw_rgb_text (PostScriptPage pspage, double red, double green,double blue, CONST char *string, CONST char *fontname, unsigned int fontsize, double xstart, double ystart, double angle)

Write a colour string to a PostScriptPage object.

Parameters:

- pspage : The PostScriptPage object.
- red : The red component value. The range is: 0.0 (dark) to 1.0 (light)
- green : The green component value. The range is: 0.0 (dark) to 1.0 (light)
- blue : The blue component value. The range is: 0.0 (dark) to 1.0 (light)
- string : The string.
- fontname : The fontname to use. If this is NULL, the default font will be used.
- fontsize : The size of the font (in millimeters).
- xstart : The x starting point (scaled from 0.0 to 1.0).
- ystart : The y starting point (scaled from 0.0 to 1.0).
- angle : The angle to rotate the text through (in degrees). Positive angles rotate counter-clockwise from horizontal.

Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe

flag psw_set_attributes (PostScriptPage pspage, ...)

Set the attributes for a PostScriptPage object.

Parameters:

- pspage : The PostScriptPage object.
- ... : The optional list of parameter attribute-key attribute-value pairs must follow. This list must be terminated with the value PSW_ATT_END. See psw_ATTRIBUTES for the list of attributes.

Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

flag psw_get_media_size (CONST char *name, double *horizontal_mm, double *vertical_mm)

Get size of a known media type.

Parameters:

- name : The name of the media size type.
- horizontal_mm : The horizontal size in millimeters is written here.
- vertical_mm : The vertical size in millimeters is written here.

Returns: TRUE if the media size is known, else FALSE.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

void psw_set_clip_areas (PostScriptPage pspage, unsigned int num_areas, CONST float *x0, CONST float *y0, CONST float *x1, CONST float *y1)

Set the clip areas.

Parameters:

- pspage : The PostScriptPage object.
- num_areas : The number of clip areas. If 0, there are no clip areas.
- x0 : The first horizontal co-ordinate array.
- y0 : The first vertical co-ordinate array.
- x1 : The second horizontal co-ordinate array.
- y1 : The second vertical co-ordinate array.

Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe

## Tables

psw_ATTRIBUTES List of attributes for PostScriptPage object

Name | Type | Meaning
PSW_ATT_END |  | End of varargs list
PSW_ATT_LINEWIDTH_MM | double | Linewidth in mm
PSW_ATT_LINEWIDTH_RELATIVE | double | Linewidth scaled to page size
PSW_ATT_THIN_LINEWIDTH_MM | double | Width of thin lines in mm
PSW_ATT_TRAY | unsigned int | Tray type, see psw_TRAY_TYPES

psw_TRAY_TYPES List of PostScript tray types

Name | Meaning
PSW_TRAY_DEFAULT | The default tray
PSW_TRAY_PAPER | The paper tray
PSW_ATT_TRAY_TRANSPARENCY | The transparency tray

Back to Karma Home Page