changelog shortlog tags branches changeset file revisions annotate raw help

Mercurial > hg > plan9front / sys/man/3/draw

revision 2: ee18c165c460
child 3220: 1cf3d5629aa0
     1.1new file mode 100755
     1.2--- /dev/null
     1.3+++ b/sys/man/3/draw
     1.4@@ -0,0 +1,791 @@
     1.5+.TH DRAW 3 
     1.6+.SH NAME
     1.7+draw \- screen graphics
     1.8+.SH SYNOPSIS
    1.10+.B bind -a #i /dev
    1.12+.B /dev/draw/new
    1.14+.BI /dev/draw/ n /ctl
    1.15+.BI /dev/draw/ n /data
    1.16+.BI /dev/draw/ n /colormap
    1.17+.BI /dev/draw/ n /refresh
    1.19+.ft L
    1.20+#include <u.h>
    1.21+#include <draw.h>
    1.23+.ta \w'ushort 'u
    1.24+ushort	BGSHORT(uchar *p)
    1.25+ulong	BGLONG(uchar *p)
    1.26+void	BPSHORT(uchar *p, ushort v)
    1.27+void	BPLONG(uchar *p, ulong v)
    1.28+.ft P
    1.32+.I draw
    1.33+device serves a three-level file system 
    1.34+providing an interface to the graphics facilities of the system.
    1.35+Each client of the device connects by opening
    1.36+.B /dev/draw/new
    1.37+and reading 12 strings, each 11 characters wide followed by a blank:
    1.38+the connection number
    1.39+.RI ( n ),
    1.40+the image id
    1.41+.RI ( q.v. )
    1.42+of the display image (always zero),
    1.44+channel format
    1.45+of the image,
    1.47+.BR min.x ,
    1.48+.BR min.y ,
    1.49+.BR max.x ,
    1.51+.B max.y
    1.52+of the display image,
    1.53+and the
    1.54+.BR min.x ,
    1.55+.BR min.y ,
    1.56+.BR max.x ,
    1.58+.B max.y 
    1.59+of the clipping rectangle. 
    1.60+The channel format string is described in 
    1.61+.IR image (6),
    1.62+and the other fields are decimal numbers.
    1.64+The client can then open the directory
    1.65+.BI /dev/draw/ n /
    1.66+to access the
    1.67+.BR ctl ,
    1.68+.BR data ,
    1.69+.BR colormap ,
    1.71+.B refresh
    1.72+files associated with the connection.
    1.74+Via the 
    1.75+.B ctl
    1.77+.B draw 
    1.78+files, the
    1.79+.I draw
    1.80+device provides access to 
    1.81+images and font caches
    1.82+in its private storage,
    1.83+as described in 
    1.84+.IR graphics (2).
    1.85+Each image is identified by a 4-byte integer, its
    1.86+.IR id .
    1.88+Reading the
    1.89+.B ctl 
    1.90+file yields 12 strings formatted as in
    1.91+.BR /dev/draw/new ,
    1.92+but for the current image rather
    1.93+than the display image.
    1.94+The current image may be set by writing a
    1.95+binary image id to the
    1.96+.B ctl
    1.99+A process can write messages to 
   1.100+.B data
   1.101+to allocate and free images, fonts, and subfonts;
   1.102+read or write portions of the images;
   1.103+and draw line segments and character
   1.104+strings in the images.
   1.105+All graphics requests are clipped to their images.
   1.106+Some messages return a response to be recovered by 
   1.107+reading the
   1.108+.B data 
   1.111+The format of messages written to
   1.112+.B data
   1.113+is a single letter
   1.114+followed by binary parameters;
   1.115+multibyte integers are transmitted with the low order byte first.
   1.117+.B BPSHORT
   1.119+.B BPLONG
   1.120+macros place correctly formatted two- and four-byte integers into a character
   1.122+.B BGSHORT
   1.124+.B BGLONG
   1.125+retrieve values from a character buffer.
   1.126+Points are two four-byte numbers:
   1.127+.IR x ,
   1.128+.IR y .
   1.129+Rectangles are four four-byte numbers: min 
   1.130+.IR x ,
   1.132+.IR y ,
   1.134+.IR x ,
   1.135+and max
   1.136+.IR y .
   1.137+Images, screens, and fonts have 32-bit identifiers.
   1.138+In the discussion of the protocol below,
   1.139+the distinction between identifier and actual image, screen, or font
   1.140+is not made, so that
   1.141+``the object
   1.142+.IR id ''
   1.143+should be interpreted as 
   1.144+``the object with identifier
   1.145+.IR id ''.
   1.146+The definitions of constants used in the description below can be found in
   1.147+.BR draw.h .
   1.149+The following requests are accepted by the
   1.150+.B data
   1.152+The numbers in brackets give the length in bytes of the parameters.
   1.153+.HP .5i
   1.154+.B A
   1.155+.IR id [4]
   1.156+.IR imageid [4]
   1.157+.IR fillid [4]
   1.158+.IR public [1]
   1.160+Allocate a new
   1.161+.B Screen
   1.163+.IR window (2))
   1.165+screen identifier
   1.166+.I id
   1.168+backing store image
   1.169+.IR imageid ,
   1.170+filling it initially
   1.171+with data from image
   1.172+.IR fillid .
   1.173+If the
   1.174+.I public
   1.175+byte is non-zero, the screen can 
   1.176+be accessed from other processes
   1.177+using the
   1.178+.B publicscreen
   1.181+.B b 
   1.182+.IR id [4]
   1.183+.IR screenid [4]
   1.184+.IR refresh [1]
   1.185+.IR chan [4]
   1.186+.IR repl [1]
   1.187+.IR r [4*4]
   1.188+.IR clipr [4*4]
   1.189+.IR color [4]
   1.191+Allocate an image with a given 
   1.192+.I id 
   1.193+on the
   1.194+screen named by
   1.195+.IR screenid .
   1.196+The image will have rectangle
   1.197+.I r 
   1.198+and clipping rectangle
   1.199+.IR clipr .
   1.201+.I repl
   1.202+is non-zero, the image's replicate 
   1.203+bit will be set (see
   1.204+.IR draw (2)).
   1.206+.I Refresh
   1.207+specifies the method to be used to draw the window
   1.208+when it is uncovered.
   1.209+.B Refbackup
   1.210+causes the server to maintain a backing store,
   1.211+.B Refnone 
   1.212+does not refresh the image,
   1.214+.B Refmesg
   1.215+causes a message to be sent via
   1.217+.B refresh 
   1.219+.RI ( q.v. ).
   1.221+The image format is described by
   1.222+.IR chan ,
   1.223+a binary version of the channel format string.
   1.224+Specifically, the image format is the catenation of up to four
   1.225+8-bit numbers, each describing a particular image channel.
   1.226+Each of these 8-bit numbers contains a channel type in its
   1.227+high nibble and a bit count in its low nibble.
   1.228+The channel type is one of
   1.229+.BR CRed ,
   1.230+.BR CGreen ,
   1.231+.BR CBlue ,
   1.232+.BR CGrey ,
   1.233+.BR CAlpha ,
   1.234+.BR CMap ,
   1.236+.BR CIgnore .
   1.238+.IR image (6).
   1.240+.I Color
   1.241+is the catenation of four 8-bit numbers
   1.242+specifying the red, green, blue, and alpha
   1.243+channels of the color that the new image should
   1.244+be initially filled with.
   1.245+The red channel is in the highest 8 bits, and
   1.246+the alpha in the lowest.
   1.247+Note that color is always in this format, independent of 
   1.248+the image format.
   1.250+.B c
   1.251+.IR dstid [4]
   1.252+.IR repl [1]
   1.253+.IR clipr [4*4]
   1.255+Change the replicate bit and clipping rectangle of the 
   1.257+.IR dstid .
   1.258+This overrides whatever settings were specified in
   1.259+the allocate message.
   1.261+.B d
   1.262+.IR dstid [4]
   1.263+.IR srcid [4]
   1.264+.IR maskid [4]
   1.265+.IR dstr [4*4]
   1.266+.IR srcp [2*4]
   1.267+.IR maskp [2*4]
   1.269+Use the 
   1.270+.B draw
   1.271+operator to combine the rectangle 
   1.272+.I dstr
   1.275+.I dstid 
   1.276+with a 
   1.277+rectangle of image
   1.278+.IR srcid ,
   1.279+using a rectangle of image
   1.280+.IR maskid
   1.281+as an alpha mask to further control blending.
   1.282+The three rectangles are congruent and aligned such that
   1.283+the upper left corner
   1.284+.I dstr
   1.285+in image
   1.286+.I dstid
   1.287+corresponds to
   1.288+the point 
   1.289+.I srcp
   1.290+in image
   1.291+.I srcid
   1.293+the point
   1.294+.I maskp
   1.295+in image
   1.296+.IR maskid .
   1.298+.IR draw (2).
   1.300+.B D
   1.301+.IR debugon [1]
   1.304+.I debugon
   1.305+is non-zero, enable debugging output.
   1.306+If zero, disable it.
   1.307+The meaning of ``debugging output'' is implementation dependent.
   1.309+.B e
   1.310+.IR dstid [4]
   1.311+.IR srcid [4]
   1.312+.IR c [2*4]
   1.313+.IR a [4]
   1.314+.IR b [4]
   1.315+.IR thick [4]
   1.316+.IR sp [2*4]
   1.317+.IR alpha [4]
   1.318+.IR phi [4]
   1.320+Draw an ellipse in image
   1.321+.I dst
   1.322+centered on the point
   1.323+.I c
   1.324+with horizontal and vertical semiaxes
   1.325+.I a
   1.327+.IR b .
   1.328+The ellipse is drawn using the image
   1.329+.IR src ,
   1.331+the point
   1.332+.I sp
   1.334+.I src
   1.335+aligned with
   1.336+.I c
   1.338+.IR dst .
   1.339+The ellipse is drawn with thickness
   1.340+.RI 1+2× thick .
   1.342+If the high bit of
   1.343+.I alpha
   1.344+is set, 
   1.345+only the arc of the ellipse from degree angles
   1.346+.I alpha
   1.348+.I phi 
   1.349+is drawn.
   1.350+For the purposes of drawing the arc,
   1.351+.I alpha
   1.352+is treated as a signed 31-bit number
   1.353+by ignoring its high bit.
   1.355+.B E
   1.356+.IR dstid [4]
   1.357+.IR srcid [4]
   1.358+.IR center [2*4]
   1.359+.IR a [4]
   1.360+.IR b [4]
   1.361+.IR thick [4]
   1.362+.IR sp [2*4]
   1.363+.IR alpha [4]
   1.364+.IR phi [4]
   1.366+Draws an ellipse or arc as the
   1.367+.B e
   1.368+message, but rather than outlining it, fills
   1.369+the corresponding sector using the image
   1.370+.IR srcid .
   1.372+.I thick 
   1.373+field is ignored, but must be non-negative.
   1.375+.B f
   1.376+.IR id [4]
   1.378+Free the resources associated with the image
   1.379+.IR id .
   1.381+.B F
   1.382+.IR id [4]
   1.384+Free the the screen with the specified
   1.385+.IR id .
   1.386+Windows on the screen must be freed separately.
   1.388+.B i
   1.389+.IR id [4]
   1.390+.IR n [4]
   1.391+.IR ascent [1]
   1.393+Treat the image
   1.394+.I id
   1.395+as a font cache of 
   1.396+.I n
   1.397+character cells, each with
   1.399+.IR ascent .
   1.401+.B l
   1.402+.IR cacheid [4]
   1.403+.IR srcid [4]
   1.404+.IR index [2]
   1.405+.IR r [4*4]
   1.406+.IR sp [2*4]
   1.407+.IR left [1]
   1.408+.IR width [1]
   1.410+Load a character into the font cache associated with image
   1.411+.I cacheid
   1.412+at cache position
   1.413+.IR index .
   1.414+The character data is drawn in rectangle
   1.415+.I r
   1.416+of the font cache image
   1.417+and is fetched from
   1.418+the congruent rectangle in image
   1.419+.I srcid
   1.420+with upper left corner
   1.421+.IR sp .
   1.422+.I Width
   1.423+specifies the width of the character\(emthe spacing from this character to the next\(emwhile
   1.424+.I left
   1.426+the horizontal distance from the left side
   1.427+of the character to the left side of the cache image.
   1.428+The dimensions of the image of the character are defined by
   1.429+.IR r .
   1.431+.B L
   1.432+.IR dstid [4]
   1.433+.IR p0 [2*4]
   1.434+.IR p1 [2*4]
   1.435+.IR end0 [4]
   1.436+.IR end1 [4]
   1.437+.IR thick [4]
   1.438+.IR srcid [4]
   1.439+.IR sp [2*4]
   1.441+Draw a line of thickness
   1.442+.RI 1+2× thick
   1.443+in image
   1.444+.I dstid
   1.445+from point
   1.446+.I p0
   1.448+.IR p1 .
   1.449+The line is drawn using the image
   1.450+.IR srcid ,
   1.451+translated so that point
   1.452+.I sp
   1.454+.I srcid
   1.455+aligns with
   1.456+.I p0
   1.458+.IR dstid .
   1.460+.I end0
   1.462+.I end1
   1.463+fields specify whether the corresponding
   1.464+line end should be a square, a disc,
   1.465+or an arrow head.
   1.467+.I line
   1.469+.IR draw (2)
   1.470+for more details.
   1.472+.B N
   1.473+.IR id [4]
   1.474+.IR in [1]
   1.475+.IR j [1]
   1.476+.IR name [ j ]
   1.479+.I in
   1.480+is non-zero, associate the image
   1.481+.I id
   1.482+with the string
   1.483+.IR name .
   1.485+.I in
   1.486+is zero and 
   1.487+.I name
   1.488+already corresponds to the
   1.490+.IR id ,
   1.491+the association is deleted.
   1.493+.B n
   1.494+.IR id [4]
   1.495+.IR j [1]
   1.496+.IR name [ j ]
   1.498+Introduce the identifier 
   1.499+.I id
   1.500+to correspond to the image named
   1.501+by the string
   1.502+.IR name .
   1.504+.B o
   1.505+.IR id [4]
   1.506+.IR r.min [2*4]
   1.507+.IR scr [2*4]
   1.509+Position the window 
   1.510+.I id
   1.511+so that its upper left corner is at the
   1.513+.I scr
   1.514+on its screen.
   1.515+Simultaneously change its internal (logical) coordinate system
   1.516+so that the point
   1.517+.I log
   1.518+corresponds to the upper left corner of the window.
   1.520+.B O
   1.521+.IR op [1]
   1.523+Set the compositing operator to
   1.524+.I op
   1.525+for the next draw operation.
   1.526+(The default is
   1.527+.BR SoverD ).
   1.529+.B p
   1.530+.IR dstid [4]
   1.531+.IR n [2]
   1.532+.IR end0 [4]
   1.533+.IR end1 [4]
   1.534+.IR thick [4]
   1.535+.IR srcid [4]
   1.536+.IR sp [2*4]
   1.537+.IR dp [2*2*(n+1)]
   1.539+Draw a polygon of thickness
   1.540+.RI 1+2× thick .
   1.541+It is conceptually equivalent to a series of
   1.542+.I n
   1.543+line-drawing messages (see
   1.544+.B L
   1.546+joining adjacent points in the list of points
   1.547+.IR dp .
   1.548+The source image
   1.549+.I srcid
   1.550+is translated so that the point
   1.551+.I sp
   1.553+.I srcid
   1.554+aligns with the first point
   1.555+in the list
   1.556+.IR dp .
   1.557+The polygon need not be closed: 
   1.558+.I end0
   1.560+.I end1
   1.561+specify the line endings for the first and
   1.562+last point on the polygon.
   1.563+All interior lines have rounded ends
   1.564+to make smooth joins.
   1.566+.B P
   1.567+.IR dstid [4]
   1.568+.IR n [2]
   1.569+.IR wind [4]
   1.570+.IR ignore [2*4]
   1.571+.IR srcid [4]
   1.572+.IR sp [2*4]
   1.573+.IR dp [2*2*(n+1)]
   1.575+Draw a polygon as the
   1.576+.B p
   1.577+message, but
   1.578+fill it rather than outlining it.
   1.579+The winding rule parameter
   1.580+.I wind
   1.581+resolves ambiguities about what to fill if the polygon is self-intersecting.
   1.583+.I wind
   1.585+.BR ~0 ,
   1.586+a pixel is inside the polygon if the polygon's winding number about the point
   1.587+is non-zero.
   1.589+.I wind
   1.591+.BR 1 ,
   1.592+a pixel is inside if the winding number is odd.
   1.593+Complementary values (0 or ~1) cause outside pixels to be filled.
   1.594+The meaning of other values is undefined.
   1.595+The polygon is closed with a line if necessary.
   1.597+.B r
   1.598+.IR id [4]
   1.599+.IR r [4*4]
   1.601+Cause the next read of the
   1.602+.B data
   1.603+file to return the image pixel data corresponding to the
   1.605+.I r
   1.606+in image
   1.607+.IR id .
   1.609+.B s
   1.610+.IR dstid [4]
   1.611+.IR srcid [4]
   1.612+.IR fontid [4]
   1.613+.IR p [2*4]
   1.614+.IR clipr [4*4]
   1.615+.IR sp [2*4]
   1.616+.IR n [2]
   1.617+.IR n*(index [2])
   1.619+Draw in the image
   1.620+.I dstid
   1.621+the text string specified by the 
   1.622+.I n 
   1.624+.I indices
   1.625+into font
   1.626+.IR fontid ,
   1.627+starting with the upper left corner at point
   1.628+.I p
   1.629+in image
   1.630+.IR dstid .
   1.631+The image drawn is taken from image
   1.632+.IR srcid ,
   1.633+translated to align
   1.634+.I sp
   1.636+.I srcid
   1.638+.I dp
   1.640+.IR dstid.
   1.641+All drawing is confined to the clipping rectangle
   1.642+.I clipr 
   1.644+.IR dstid .
   1.646+.B x
   1.647+.IR dstid [4]
   1.648+.IR srcid [4]
   1.649+.IR fontid [4]
   1.650+.IR dp [2*4]
   1.651+.IR clipr [4*4]
   1.652+.IR sp [2*4]
   1.653+.IR n [2]
   1.654+.IR bgid [4]
   1.655+.IR bp [2*4]
   1.656+.IR n*(index [2])
   1.658+Like the string drawing 
   1.659+.B s
   1.660+command, but fill the background of each character
   1.661+with pixels from image
   1.662+.IR bgid .
   1.663+The image
   1.664+.I bgid
   1.665+is translated so that the point
   1.666+.I bp
   1.667+aligns with the
   1.669+.I dp
   1.671+.IR dstid .
   1.673+.B S
   1.674+.IR id [4]
   1.675+.IR chan [4]
   1.676+Attach to the public screen with the specified
   1.677+.IR id .
   1.678+It is an error if the screen does not exist, is not public, or does not
   1.679+have the channel descriptor
   1.680+.I chan
   1.681+for its associated image.
   1.683+.B t
   1.684+.IR top [1]
   1.685+.IR n [2]
   1.686+.IR n*id [4]
   1.689+.I n
   1.690+windows to the top (if
   1.691+.I t
   1.692+is non-zero) or bottom (if
   1.693+.I t
   1.694+is zero) of the window stack.
   1.695+The window is specified by the list of
   1.696+.I n
   1.698+.IR id s
   1.699+are moved as a group, maintaining their own order within the stack.
   1.701+.B v
   1.703+Flush changes from a soft screen, if any, to the display buffer.
   1.705+.B y
   1.706+.IR id [4]
   1.707+.IR r [4*4]
   1.708+.IR buf [x*1]
   1.710+.ti -0.5i
   1.711+.B Y
   1.712+.IR id [4]
   1.713+.IR r [4*4]
   1.714+.IR buf [x*1]
   1.716+Replace the rectangle 
   1.717+.I r
   1.718+of pixels in image
   1.719+.I id
   1.720+with the pixel data in 
   1.721+.IR buf .
   1.722+The pixel data must be in the format dictated by
   1.723+.IR id 's
   1.724+image channel descriptor (see
   1.725+.IR image (6)).
   1.727+.B y
   1.728+message uses uncompressed data,
   1.729+while the
   1.730+.B Y
   1.731+message uses compressed data. 
   1.732+In either case, 
   1.733+it is an error to include more data than necessary.
   1.735+Reading the
   1.736+.B colormap
   1.737+returns the system color map used on 8-bit displays.
   1.738+Each color map entry consists of a single line containing
   1.739+four space-separated decimal strings.
   1.740+The first is an index into the map, and the remaining three are
   1.741+the red, green, and blue values associated with that index.
   1.742+The color map can be changed by writing entries in the
   1.743+above format to
   1.745+.B colormap
   1.747+Note that changing the system color map 
   1.748+does not change the color map used for
   1.749+calculations involving
   1.750+.B m8
   1.751+images, which is immutable.
   1.754+.B refresh
   1.755+file is read-only.
   1.756+As windows owned by the client are uncovered,
   1.757+if they cannot be refreshed by the server (such as when they have
   1.758+refresh functions associated with them), a message is made available
   1.759+on the
   1.760+.B refresh
   1.761+file reporting what needs to be repainted by the client.
   1.762+The message has five decimal integers formatted as in the
   1.763+.B ctl
   1.764+message: the image id of the window and the coordinates of the rectangle
   1.765+that should be refreshed.
   1.766+.SH SOURCE
   1.767+.B /sys/src/9/port/devdraw.c
   1.769+.B /sys/src/libmemdraw
   1.771+Most messages to
   1.772+.B draw
   1.773+can return errors;
   1.774+these can be detected by a system call error
   1.775+on the
   1.776+.IR write (see
   1.777+.IR read (2))
   1.778+of the data containing the erroneous message.
   1.779+The most common error is a failure to allocate
   1.780+because of insufficient free resources.  Most other errors occur
   1.781+only when the protocol is mishandled by the application.
   1.782+.IR Errstr (2)
   1.783+will report details.
   1.784+.SH BUGS
   1.786+.B Refmesg
   1.787+refresh method is not fully implemented.
   1.790+.B colormap
   1.791+files only reference the system color map, and as 
   1.792+such should be called
   1.793+.B /dev/colormap
   1.794+rather than
   1.795+.BI /dev/draw/ n /colormap\f1.