raster(3)

NAME
raster - simple low-level raster graphics library

SYNOPSIS
ld ... -lraster

DESCRIPTION

Raster is simple raster graphics package. It's basically a redesigned and reimplemented edition of Sun's old pixrect library. It does rectangle operations (bit-blits), points, lines, text (using vfont files), stencils, tiling, image file i/o (using Sun rasterfiles), etc.

There is also a subsidiary library that provides an API very similar to pixrect. You can use this to keep your pixrect-based programs going under Solaris 2.x, where Sun has decided to get rid of pixrect.

BIT-BLIT OPERATIONS

    int raster_op( struct raster* dst, int dx, int dy, int w,
        int h, int rop, struct raster* src, int sx, int sy );
Performs a bitblit. Returns 0 on success, -1 on failure.

    int raster_op_noclip( struct raster* dst, int dx, int dy,
        int w, int h, int rop, struct raster* src, int sx,
        int sy );
Bitblit without clipping. Returns 0 on success, -1 on failure.

    int raster_replsrc( struct raster* dst, int dx, int dy,
        int w, int h, int rop, struct raster* src, int sx,
        int sy );
Tiles the src to fit the dst. Returns 0 on success, -1 on failure. Only implements RAS_SRC.

    int raster_batchop( struct raster* dst, int dx, int dy,
        int rop, struct raster* srcs[], int sxs[], int sys[],
        int count );
Blits a bunch of sources sequentially into one destination.

    int raster_stencil( struct raster* dst, int dx, int dy,
        int w, int h, int rop, struct raster* sten, int stx,
        int sty, struct raster* src, int sx, int sy );
Draws src through sten onto dst. sten must be of depth 1.

    int raster_point( struct raster* r, int x, int y, int rop );
Draws a single point into a raster. Compare with raster_put(). Returns 0 on success, -1 on failure.

    int raster_point_noclip( struct raster* r, int x, int y,
        int rop );
Draws a single point into a raster, without clipping. Returns 0 on success, -1 on failure.

RASTER ROUTINES

    struct raster* raster_alloc( int width, int height,
        int depth );
Allocates a raster. Returns (struct raster*) 0 on failure.

    void raster_free( struct raster* r );
Frees/closes a raster.

    u_long* RAS_ADDR( struct raster* r, int x, int y )
Gets the longword address of a pixel.

    int raster_get( struct raster* r, int x, int y );
Gets a single pixel from a raster. Returns value on success, -1 on failure.

    int raster_put( struct raster* r, int x, int y, int v );
Puts a single pixel into a raster. Compare with raster_point(). Returns 0 on success, -1 on failure.

    int raster_line( struct raster* r, int x0, int y0, int x1,
        int y1, int rop );
Draws a line into a raster. Returns 0 on success, -1 on failure.

    int raster_line_noclip( struct raster* r, int x0, int y0,
        int x1, int y1, int rop );
Draws a line into a raster, without clipping. Returns 0 on success, -1 on failure.

    int raster_spline3( struct raster* r, int x0, int y0,
        int x1, int y1, int x2, int y2, int rop );
Draws a three-point spline into a raster. Returns 0 on success, -1 on failure.

    struct raster* raster_subregion( struct raster* r, int x,
        int y, int width, int height );
Makes a raster that points to a region of another. Returns (struct raster*) 0 on failure.

    struct raster* raster_static( int width, int height,
        int depth, u_long* data );
Turns static data into a raster. Returns (struct raster*) 0 on failure.

TEXT ROUTINES

    struct raster_font* raster_fontopen( char* fontname );
Opens a font. Returns (struct raster_font*) 0 on failure.

    struct raster_font* raster_defaultfont( void );
Returns the default font. Returns (struct raster_font*) 0 on failure.

    int raster_text( struct raster* r, int x, int y, int rop,
        struct raster_font* rf, char* text );
Draws text. Returns 0 on success, -1 on failure.

    int raster_textn( struct raster* r, int x, int y, int rop,
        struct raster_font* rf, char* text, int len );
Draws n characters of text. Returns 0 on success, -1 on failure.

    int raster_textnsize( struct raster_font* rf, char* text,
        int n, int* xP, int* yP, int* wP, int* hP );
Measures n characters of text. Returns 0 on success, -1 on failure.

    void raster_fontclose( struct raster_font* rf );
Closes a font.

    int raster_ttext( struct raster* r, int x, int y, int rop,
        struct raster_font* rf, char* text );
Draws text with transparent background. Returns 0 on success, -1 on failure.

    int raster_ttextn( struct raster* r, int x, int y,
        int rop, struct raster_font* rf, char* text, int len );
Draws n characters of text with transparent background. Returns 0 on success, -1 on failure.

FRAME BUFFER ROUTINES

    struct raster* raster_open( char* fbname );
Opens a frame buffer as a raster. Returns (struct raster*) 0 on failure.

    struct raster* raster_coloropen( void );
Opens a color frame buffer if there is one. Returns (struct raster*) 0 on failure.

    int raster_video_off( struct raster* r );
Blanks the screen. Returns 0 on success, -1 on failure.

    int raster_video_on( struct raster* r );
Re-enables video. Returns 0 on success, -1 on failure.

    struct raster_colormap* raster_colormap_alloc( int len );
Allocates a colormap structure, returns 0 on failure.

    struct raster_colormap* raster_colormap_get( struct raster* r );
Allocates a colormap structure and returns the frame buffer's current colormap, or (struct raster_colormap*) 0 on failure. The raster must be one returned by raster_open(), not raster_alloc().

    int raster_colormap_set( struct raster* r,
        struct raster_colormap* cm );
Sets a frame buffer's colormap. The raster must be one returned by raster_open(), not raster_alloc(). Returns 0 on success, -1 on failure.

    void raster_colormap_free( struct raster_colormap* cm );
Frees a colormap.

RASTERFILE READ/WRITE ROUTINES

    struct raster* raster_read( FILE* f,
        struct raster_colormap** cmP );
Allocates a raster and reads the contents from a file. Returns (struct raster*) 0 on failure. If there's a colormap in the file, it gets allocated and returned in cmP; otherwise, cmP is 0.

    int raster_write( FILE* f, struct raster* r, int rt,
        struct raster_colormap* cm );
Writes a raster to a file. The colormap is optional. Returns 0 on success, -1 on failure. rt is the file type - one of RT_STANDARD, RT_BYTE_ENCODED, RT_FORMAT_RGB.

C STRUCT WRITE ROUTINES

    int raster_dump( FILE* f, struct raster* r, char* name );
Writes a raster as C structs. Returns 0 on success, -1 on failure.

    int raster_fontdump( FILE* f, struct raster_font* rf,
        char* name );
Writes a font as C structs. Returns 0 on success, -1 on failure.

THE ROP ARGUMENT

Many of the routines take an argument called "rop". This controls what sort of raster operation gets done. A rop can be some boolean combination of RAS_SRC and RAS_DST. For instance, just RAS_SRC means copy the source to the destination without modification. RAS_SRC|RAS_DST means "or" the source and destination together, while "xor" would be specified as RAS_SRC^RAS_DST. The RAS_NOT macro should be used to express negation - RAS_NOT(RAS_SRC)&RAS_DST would "and" the complement of the source with the destination.

Or, you can just use one of the pre-defined rops besides the basic RAS_SRC and RAS_DST. There are only 16 possible combinations, so all 16 are defined:
    RAS_CLEAR           turn all bits off (white)
    RAS_NOTOR           ! ( src | dst )
    RAS_NOTSRC_AND_DST  ! src & dst
    RAS_INVERTSRC       ! src
    RAS_SRC_AND_NOTDST  src & !dst
    RAS_INVERT          ! dst
    RAS_XOR             src ^ dst
    RAS_NOTAND          ! ( src & dst )
    RAS_AND             src & dst
    RAS_NOTXOR          ! ( src ^ dst )
    RAS_DST             dst
    RAS_NOTSRC_OR_DST   ! src | dst
    RAS_SRC             src
    RAS_SRC_OR_NOTDST   src | ! dst
    RAS_OR              src | dst
    RAS_SET             turn all bits on (black)
For color rasters, you specify the color of the operation by simply ORing RAS_COLOR(color) into the rop.

SEE ALSO
pixrect(3), screendump(1), screenload(1), spf3(1), squig(1)

AUTHOR
Copyright (C) 1993 by Jef Poskanzer <jef@netcom.com>.