.\" This file is in the public domain.
.Dd May 15, 1999
.Dt LIBROP 3
.Os NetBSD 1.4BETA
.Sh NAME
.Nm rop_create ,
.Nm rop_free ,
.Nm rop_w ,
.Nm rop_h ,
.Nm rop_loadrow ,
.Nm rop_fetchrow ,
.Nm rop_rop ,
.Nm rop_getpixel ,
.Nm rop_putpixel ,
.Nm rop_ropbit ,
.Nm rop_transpose ,
.Nm rop_xputimage
.Nd rasterop routines
.Sh SYNOPSIS
.Fd #include <rop.h>
.br
.Nm cc
.Op Ar arguments
.Fl lrop
.br
.Ft ROP_AREA *
.Fn rop_create "unsigned int width" "unsigned int height"
.Ft void
.Fn rop_free "ROP_AREA *area"
.Ft unsigned int
.Fn rop_w "const ROP_AREA *area"
.Ft unsigned int
.Fn rop_h "const ROP_AREA *area"
.Ft int
.Fn rop_getpixel "const ROP_AREA *area" "unsigned int x" "unsigned int y"
.Ft void
.Fn rop_putpixel "ROP_AREA *area" "unsigned int x" "unsigned int y" "unsigned int v"
.Ft void
.Fn rop_loadrow "ROP_AREA *area" "unsigned int y" "const unsigned char *data"
.Ft void
.Fn rop_fetchrow "const ROP_AREA *area" "unsigned int y" "unsigned char *data"
.Ft void
.Fo rop_rop
.Fa "const ROP_AREA *src"
.Fa "unsigned int srcx"
.Fa "unsigned int srcy"
.Fa "unsigned int w"
.Fa "unsigned int h"
.Fa "ROP_AREA *dst"
.Fa "unsigned int dstx"
.Fa "unsigned int dsty"
.Fa "unsigned int op"
.Fc
.Ft unsigned int
.Fn rop_ropbit "unsigned int op" "unsigned int srcbit" "unsigned int dstbit"
.Ft ROP_AREA *
.Fn rop_transpose "const ROP_AREA *src" "ROP_AREA *dst" "int how"
.Ft void
.Fo rop_xputimage
.Fa "Display *disp"
.Fa "Drawable target"
.Fa "GC gc"
.Fa "XImage *img"
.Fa "const ROP_AREA *area"
.Fa "unsigned int srcx"
.Fa "unsigned int srcy"
.Fa "unsigned int dstx"
.Fa "unsigned int dsty"
.Fa "unsigned int w"
.Fa "unsigned int h"
.Fc
.Sh DESCRIPTION
These functions are a general-purpose one-bit-per-pixel rasterop
package.  The basic type is an opaque structure typedef
.Dv ROP_AREA ,
whose contents are not directly accessible.  Such objects are created
with
.Fn rop_create ,
which takes a pair of dimensions and returns an object with those
dimensions (its initial contents are unspecified); they are freed with
.Fn rop_free ,
which takes an existing
.Dv ROP_AREA
object and frees the storage associated with it.  When the
.Fn rop_free
call is made, the pointer passed becomes invalid and must never be used
again.
.Pp
Functions
.Fn rop_w
and
.Fn rop_h
are provided to retrieve the dimensions of an area.  The contents can
be set one pixel at a time with
.Fn rop_putpixel
(the low bit of the last argument is used) and inspected one pixel at a
time with
.Fn rop_getpixel
(which always returns 0 or 1); an entire row can be set or fetched with
.Fn rop_loadrow
or
.Fn rop_fetchrow ,
which work with pixel data stored as an array of
.\"
.\" How the fsck do I get
.\"	`unsigned char's,
.\" here?  The following don't work:
.\"
.\"	.Sq unsigned char s ,
.\"
.\"	.Sq unsigned char Ns s ,
.\"
.\"	.Sm off
.\"	.Sq unsigned char
.\"	s,
.\"	.Sm on
.\"
unsigned chars,
with the leftmost pixel in each byte stored as the most-significant
bit.
.Fn rop_loadrow
and
.Fn rop_fetchrow
access only the minimum number of bytes necessary to represent an
entire row, regardless of how the data rows may be stored internally.
If the number of pixels is not a multiple of 8, the
.Sq extra
(low-order) bits of the last byte are ignored by
.Fn rop_loadrow
and will be written with meaningless values by
.Fn rop_fetchrow .
.Pp
The central function of the package is
.Fn rop_rop ,
which combines two rectangular (sub)areas of equal dimensions with one
of the 16 possible two-argument Boolean functions.  The
.Fa w
and
.Fa h
arguments specify the width and height of the rectangular areas.  The
.Sq src
and
.Sq dst
arguments specify the rasterop area and position of the two rectangles,
with the result being written back into the
.Sq dst
rectangle.
.Fa src
and
.Fa dst
may be the same, and if so the areas may overlap partially or entirely.
The area is clipped so as to remain within both
.Fa src
and
.Fa dst ,
by reducing the width and height if necessary.  The last argument,
.Fa op ,
specifies which of the 16 possible operations is to be performed.
Manifest constants are provided for all 16 operations.  The prefix
.Sq N
in these names indicates complementation and applies to the portion it
is attached to, either the operation (indicating complementation after
the operation is performed) or to one of the arguments.
.Bl -item -compact -offset indent
.It
.Dv ROP_CLR
.It
.Dv ROP_SRC_NOR_DST
.It
.Dv ROP_SRC_AND_NDST
.It
.Dv ROP_NDST
.It
.Dv ROP_NSRC_AND_DST
.It
.Dv ROP_NSRC
.It
.Dv ROP_SRC_XOR_DST
.It
.Dv ROP_SRC_NAND_DST
.It
.Dv ROP_SRC_AND_DST
.It
.Dv ROP_SRC_NXOR_DST
.It
.Dv ROP_SRC
.It
.Dv ROP_SRC_OR_NDST
.It
.Dv ROP_DST
.It
.Dv ROP_NSRC_OR_DST
.It
.Dv ROP_SRC_OR_DST
.It
.Dv ROP_SET
.El
Additionally, their values are such that one can use the C operators
\&&, \*(Ba, \&^, and \&~ with
.Dv ROP_SRC
and
.Dv ROP_DST
to construct an
.Fa op
argument, with the obvious semantics (eg, using
.Dv ROP_SRC&~ROP_DST
will be equivalent to using
.Dv ROP_SRC_AND_NDST ) .
Suitable types for storing raster operations are
.Sq int
and
.Sq unsigned int .
.Pp
.Fn rop_ropbit
is also provided to perform a single-bit operation, should this be
convenient; it is semantically equivalent to constructing two 1x1
areas, storing the two bits in them, calling
.Fn rop_rop ,
and retrieving the result, but is much faster and more convenient.
.Pp
.Fn rop_transpose
performs various operations that convert an X-by-Y area into a Y-by-X
area.  The
.Fa src
area is transformed into the
.Fa dst
area.  If
.Fa dst
is a nil pointer, a new area is allocated with
.Fn rop_create ;
otherwise, the
.Fa dst
area must already be an area of the correct size.  In either case, the
actual destination area is returned.  In case of an error (if
.Fa dst
is nil and
.Fn rop_create
fails, or if
.Fa dst
is supplied and the wrong size), a nil pointer is returned.  Note that
.Fa dst
and
.Fa src
must be different, even if the width and height are equal.  The
.Fa how
argument indicates which of four transformations is to be performed:
.Bl -tag -width indent
.It Dv ROP_TR_XY
The image is transformed as if reflected about the Y=X line.
.It Dv ROP_TR_NXY
The image is transformed as if reflected about the Y=-X line (and then
translated back into the first quadrant).
.It Dv ROP_TR_CW
The images is rotated 90 degrees clockwise.
.It Dv ROP_TR_CCW
The images is rotated 90 degrees counter-clockwise.
.El
.Pp
For programs using this library in conjunction with The X11 Window
System,
.Fn rop_xputimage
is provided.  It performs the equivalent to an
.Xr XPutImage 3
from a rasterop area; the caller must create and pass in an XImage
pointer, which
.Fn rop_xputimage
will modify if necessary to match the representation it happens to be
using for the rasterop area.  The rest of the arguments are passed
directly on to
.Xr XPutImage 3 .
Note that because declaring this function requires some Xlib types, and
not every program wants the Xlib header files included, this
declaration is done only when it appears that the Xlib headers have
already been included, or if the preprocessor symbol
.Dv ROP_USE_X
is defined when
.Aq Pa rop.h
is included.  The relevant routine is in its own object file, as well,
so that if it is not used, no reference to
.Xr XPutImage 3
will be generated.
.Sh ERRORS
If
.Fn rop_create
cannot allocate enough memory for a new area, it returns a nil pointer.
Except for erroneous calls, such as passing as a rasterop area pointer
a value that was not obtained from
.Fn rop_create
or passing a too-small buffer to
.Fn rop_fetchrow ,
this is the only failure case possible.
.Pp
Passing an out-of-range coordinate to
.Fn rop_loadrow ,
.Fn rop_fetchrow ,
or
.Fn rop_putpixel
causes the function to do nothing; passing an out-of-range coordinate
to
.Fn rop_getpixel
returns zero.
.Fn rop_rop
clips the area it operates on to the intersection of the source
rasterop area, the destination rasterop area, and the specified
rectangle; if the result is empty, it does nothing.
.Pp
The operation argument to
.Fn rop_rop
and
.Fn rop_ropbit
must be one of the 16 provided manifest constants, or a value which can
be constructed from one or more of them with the C operators mentioned
above; if this is not true, some operation will be performed, but which
one is unspecified.
.Sh BUGS
.Pp
Code blindly assumes 8-bit
.Do
char
.Dc Ns s.
.Sh AUTHOR
der Mouse,
.Aq mouse@rodents.montreal.qc.ca .