.TH DRAW 3 .SH NAMEdraw \- screen graphics.SH SYNOPSIS.EX.B bind -a #i /dev .B /dev/draw/new .BI /dev/draw/ n /ctl.BI /dev/draw/ n /data.ig.BI /dev/draw/ n /colormap...BI /dev/draw/ n /refresh .EE.SH DESCRIPTIONThe.I drawdevice serves a three-level file system providing an interface to the graphics facilities of the system.The Limbo Draw module (see.IR draw-intro (2))implements its functions using this device.Each client of the device connects by opening.B /dev/draw/newand reading 12 strings, each 11 characters wide followed by a blank:the connection number.RI ( n ),the image id.RI ( q.v. )of the display image (always zero),thechannel formatof the image,the.BR min.x ,.BR min.y ,.BR max.x ,and.B max.yof the display image,and the.BR min.x ,.BR min.y ,.BR max.x ,and.B max.y of the clipping rectangle. The channel format string is described in .IR image (6),and the other fields are decimal numbers..PPThe client can then open the directory.BI /dev/draw/ n /to access the.BR ctl ,.BR data ,.ig.BR colormap ,..and.B refreshfiles associated with the connection..PPVia the .B ctland.B draw files, the.I drawdevice provides access to images and font cachesin its private storage,as described in .IR draw-intro (2).Each image is identified by a 4-byte integer, its.IR id ..PPReading the.B ctl file yields 12 strings formatted as in.BR /dev/draw/new ,but for the current image ratherthan the display image.The current image may be set by writing abinary image id to the.B ctlfile..PPA process can write messages to .B datato allocate and free images, fonts, and subfonts;read or write portions of the images;and draw line segments and characterstrings in the images.All graphics requests are clipped to their images.Some messages return a response to be recovered by reading the.B data file..PPThe.B drawdevice provides three types of graphical resource: Images, Screens and Fonts.Resource instances have an identification number.Screen identifiers are global to the device.All other identifiers are local to each client..PPImage is the fundamental resource type on which all drawing primitivesare performed.At client connection the physical display is represented by Image 0..PPA Screen manages a set of (overlapping) Images, handlingZ-order and position manipulation and the refreshing of regionsuncovered by such operations.When a Screen is created it is associated with an Image on whichto render itself.New images can be associated with a screen when they are created; theyare then treated as windows on that screen.Screens can be marked as.IR public ,meaning that other clients can import their ID and create new windowson them..PPA Font is an image with associated character data.The Font image provides the bitmap of all the characters in theFont; the character data is used by the string command to rendercharacters from the image..SS "Command messages".PPThe format of messages written to.B datais a single letterfollowed by binary parameters;multibyte integers are transmitted with the low order byte first.Points are two four-byte numbers:.IR x ,.IR y .Rectangles are four four-byte numbers: min .IR x ,min.IR y ,max.IR x ,and max.IR y .Images, screens, and fonts have 32-bit identifiers.In the discussion of the protocol below,the distinction between identifier and actual image, screen, or fontis not made, so that``the object.IR id ''should be interpreted as ``the object with identifier.IR id ''.The definitions of constants used in the description below can be found in.BR /module/draw.mor.BR /include/draw.h ..PPThe following requests are accepted by the.B datafile.The numbers in brackets give the length in bytes of the parameters..HP .5i.B A.IR id [4].IR imageid [4].IR fillid [4].IR public [1].brAllocate a new.B Screen(see.IR draw-display (2))withscreen identifier.I idusingbacking store image.IR imageid ,filling it initiallywith data from image.IR fillid .If the.I publicbyte is non-zero, the screen can be accessed from other processesusing the.B publicscreeninterface..HP.B b .IR id [4].IR screenid [4].IR refresh [1].IR chan [4].IR repl [1].IR r [4*4].IR clipr [4*4].IR color [4].brAllocate an image with a given .I id on thescreen named by.IR screenid .The image will have rectangle.I r and clipping rectangle.IR clipr .If .I replis non-zero, the image's replicate bit will be set (see.IR draw (2))..IP.I Refreshspecifies the method to be used to draw the windowwhen it is uncovered..B Refbackupcauses the server to maintain a backing store,.B Refnone does not refresh the image,and.B Refmesgcauses a message to be sent viathe.B refresh file.RI ( q.v. )..IPThe image format is described by.IR chan ,a binary version of the channel format string.Specifically, the image format is the catenation of up to four8-bit numbers, each describing a particular image channel.Each of these 8-bit numbers contains a channel type in itshigh nibble and a bit count in its low nibble.The channel type is one of.BR CRed ,.BR CGreen ,.BR CBlue ,.BR CGrey ,.BR CAlpha ,.BR CMap ,and.BR CIgnore .See.IR image (6)..IP.I Coloris the catenation of four 8-bit numbersspecifying the red, green, blue, and alphachannels of the color that the new image shouldbe initially filled with.The red channel is in the highest 8 bits, andthe alpha in the lowest.Note that color is always in this format, independent of the image format..HP.B c.IR dstid [4].IR repl [1].IR clipr [4*4].brChange the replicate bit and clipping rectangle of the image.IR dstid .This overrides whatever settings were specified inthe allocate message..HP.B d.IR dstid [4].IR srcid [4].IR maskid [4].IR dstr [4*4].IR srcp [2*4].IR maskp [2*4].brUse the .B drawoperator to combine the rectangle .I dstrof image.I dstid with a rectangle of image.IR srcid ,using a rectangle of image.IR maskidas an alpha mask to further control blending.The three rectangles are congruent and aligned such thatthe upper left corner.I dstrin image.I dstidcorresponds tothe point .I srcpin image.I srcidandthe point.I maskpin image.IR maskid .See.IR draw-image (2)..HP.B D.IR debugon [1].brIf.I debugonis non-zero, enable debugging output.If zero, disable it.The meaning of ``debugging output'' is implementation dependent..HP.B e.IR dstid [4].IR srcid [4].IR c [2*4].IR a [4].IR b [4].IR thick [4].IR sp [2*4].IR alpha [4].IR phi [4].brDraw an ellipse in image.I dstcentered on the point.I cwith horizontal and vertical semiaxes.I aand.IR b .The ellipse is drawn using the image.IR src ,withthe point.I spin .I srcaligned with.I cin.IR dst .The ellipse is drawn with thickness.RI 1+2× thick ..IPIf the high bit of.I alphais set, only the arc of the ellipse from degree angles.I alphato.I phi is drawn.For the purposes of drawing the arc,.I alphais treated as a signed 31-bit numberby ignoring its high bit..HP.B E.IR dstid [4].IR srcid [4].IR center [2*4].IR a [4].IR b [4].IR thick [4].IR sp [2*4].IR alpha [4].IR phi [4].brDraws an ellipse or arc as the.B emessage, but rather than outlining it, fillsthe corresponding sector using the image.IR srcid .The .I thick field is ignored, but must be non-negative..HP.B f.IR id [4].brFree the resources associated with the image.IR id ..HP.B F.IR id [4].brFree the the screen with the specified.IR id .Windows on the screen must be freed separately..HP.B i.IR id [4].IR n [4].IR ascent [1].brTreat the image.I idas a font cache of .I ncharacter cells, each withascent.IR ascent ..HP.B l.IR cacheid [4].IR srcid [4].IR index [2].IR r [4*4].IR sp [2*4].IR left [1].IR width [1].brLoad a character into the font cache associated with image.I cacheidat cache position.IR index .The character data is drawn in rectangle.I rof the font cache imageand is fetched fromthe congruent rectangle in image.I srcidwith upper left corner.IR sp ..I Widthspecifies the width of the character\(emthe spacing from this character to the next\(emwhile.I leftspecifiesthe horizontal distance from the left sideof the character to the left side of the cache image.The dimensions of the image of the character are defined by.IR r ..HP.B L.IR dstid [4].IR p0 [2*4].IR p1 [2*4].IR end0 [4].IR end1 [4].IR thick [4].IR srcid [4].IR sp [2*4].brDraw a line of thickness.RI 1+2× thickin image.I dstidfrom point.I p0to.IR p1 .The line is drawn using the image.IR srcid ,translated so that point.I spin.I srcidaligns with.I p0in .IR dstid .The .I end0and.I end1fields specify whether the correspondingline end should be a square, a disc,or an arrow head.See .I linein.IR draw-image (2)for more details..HP.B N.IR id [4].IR in [1].IR j [1].IR name [ j ].brIf .I inis non-zero, associate the image.I idwith the string.IR name .If .I inis zero and Lines 1–500 of 816. Load more
.TH DRAW 3 .SH NAME draw \- screen graphics .SH SYNOPSIS .EX .B bind -a #i /dev .B /dev/draw/new .BI /dev/draw/ n /ctl .BI /dev/draw/ n /data .ig .BI /dev/draw/ n /colormap .. .BI /dev/draw/ n /refresh .EE .SH DESCRIPTION The .I draw device serves a three-level file system providing an interface to the graphics facilities of the system. The Limbo Draw module (see .IR draw-intro (2)) implements its functions using this device. Each client of the device connects by opening .B /dev/draw/new and reading 12 strings, each 11 characters wide followed by a blank: the connection number .RI ( n ), the image id .RI ( q.v. ) of the display image (always zero), the channel format of the image, the .BR min.x , .BR min.y , .BR max.x , and .B max.y of the display image, and the .BR min.x , .BR min.y , .BR max.x , and .B max.y of the clipping rectangle. The channel format string is described in .IR image (6), and the other fields are decimal numbers. .PP The client can then open the directory .BI /dev/draw/ n / to access the .BR ctl , .BR data , .ig .BR colormap , .. and .B refresh files associated with the connection. .PP Via the .B ctl and .B draw files, the .I draw device provides access to images and font caches in its private storage, as described in .IR draw-intro (2). Each image is identified by a 4-byte integer, its .IR id . .PP Reading the .B ctl file yields 12 strings formatted as in .BR /dev/draw/new , but for the current image rather than the display image. The current image may be set by writing a binary image id to the .B ctl file. .PP A process can write messages to .B data to allocate and free images, fonts, and subfonts; read or write portions of the images; and draw line segments and character strings in the images. All graphics requests are clipped to their images. Some messages return a response to be recovered by reading the .B data file. .PP The .B draw device provides three types of graphical resource: Images, Screens and Fonts. Resource instances have an identification number. Screen identifiers are global to the device. All other identifiers are local to each client. .PP Image is the fundamental resource type on which all drawing primitives are performed. At client connection the physical display is represented by Image 0. .PP A Screen manages a set of (overlapping) Images, handling Z-order and position manipulation and the refreshing of regions uncovered by such operations. When a Screen is created it is associated with an Image on which to render itself. New images can be associated with a screen when they are created; they are then treated as windows on that screen. Screens can be marked as .IR public , meaning that other clients can import their ID and create new windows on them. .PP A Font is an image with associated character data. The Font image provides the bitmap of all the characters in the Font; the character data is used by the string command to render characters from the image. .SS "Command messages" .PP The format of messages written to .B data is a single letter followed by binary parameters; multibyte integers are transmitted with the low order byte first. Points are two four-byte numbers: .IR x , .IR y . Rectangles are four four-byte numbers: min .IR x , min .IR y , max .IR x , and max .IR y . Images, screens, and fonts have 32-bit identifiers. In the discussion of the protocol below, the distinction between identifier and actual image, screen, or font is not made, so that ``the object .IR id '' should be interpreted as ``the object with identifier .IR id ''. The definitions of constants used in the description below can be found in .BR /module/draw.m or .BR /include/draw.h . .PP The following requests are accepted by the .B data file. The numbers in brackets give the length in bytes of the parameters. .HP .5i .B A .IR id [4] .IR imageid [4] .IR fillid [4] .IR public [1] .br Allocate a new .B Screen (see .IR draw-display (2)) with screen identifier .I id using backing store image .IR imageid , filling it initially with data from image .IR fillid . If the .I public byte is non-zero, the screen can be accessed from other processes using the .B publicscreen interface. .HP .B b .IR id [4] .IR screenid [4] .IR refresh [1] .IR chan [4] .IR repl [1] .IR r [4*4] .IR clipr [4*4] .IR color [4] .br Allocate an image with a given .I id on the screen named by .IR screenid . The image will have rectangle .I r and clipping rectangle .IR clipr . If .I repl is non-zero, the image's replicate bit will be set (see .IR draw (2)). .IP .I Refresh specifies the method to be used to draw the window when it is uncovered. .B Refbackup causes the server to maintain a backing store, .B Refnone does not refresh the image, and .B Refmesg causes a message to be sent via the .B refresh file .RI ( q.v. ). .IP The image format is described by .IR chan , a binary version of the channel format string. Specifically, the image format is the catenation of up to four 8-bit numbers, each describing a particular image channel. Each of these 8-bit numbers contains a channel type in its high nibble and a bit count in its low nibble. The channel type is one of .BR CRed , .BR CGreen , .BR CBlue , .BR CGrey , .BR CAlpha , .BR CMap , and .BR CIgnore . See .IR image (6). .IP .I Color is the catenation of four 8-bit numbers specifying the red, green, blue, and alpha channels of the color that the new image should be initially filled with. The red channel is in the highest 8 bits, and the alpha in the lowest. Note that color is always in this format, independent of the image format. .HP .B c .IR dstid [4] .IR repl [1] .IR clipr [4*4] .br Change the replicate bit and clipping rectangle of the image .IR dstid . This overrides whatever settings were specified in the allocate message. .HP .B d .IR dstid [4] .IR srcid [4] .IR maskid [4] .IR dstr [4*4] .IR srcp [2*4] .IR maskp [2*4] .br Use the .B draw operator to combine the rectangle .I dstr of image .I dstid with a rectangle of image .IR srcid , using a rectangle of image .IR maskid as an alpha mask to further control blending. The three rectangles are congruent and aligned such that the upper left corner .I dstr in image .I dstid corresponds to the point .I srcp in image .I srcid and the point .I maskp in image .IR maskid . See .IR draw-image (2). .HP .B D .IR debugon [1] .br If .I debugon is non-zero, enable debugging output. If zero, disable it. The meaning of ``debugging output'' is implementation dependent. .HP .B e .IR dstid [4] .IR srcid [4] .IR c [2*4] .IR a [4] .IR b [4] .IR thick [4] .IR sp [2*4] .IR alpha [4] .IR phi [4] .br Draw an ellipse in image .I dst centered on the point .I c with horizontal and vertical semiaxes .I a and .IR b . The ellipse is drawn using the image .IR src , with the point .I sp in .I src aligned with .I c in .IR dst . The ellipse is drawn with thickness .RI 1+2× thick . .IP If the high bit of .I alpha is set, only the arc of the ellipse from degree angles .I alpha to .I phi is drawn. For the purposes of drawing the arc, .I alpha is treated as a signed 31-bit number by ignoring its high bit. .HP .B E .IR dstid [4] .IR srcid [4] .IR center [2*4] .IR a [4] .IR b [4] .IR thick [4] .IR sp [2*4] .IR alpha [4] .IR phi [4] .br Draws an ellipse or arc as the .B e message, but rather than outlining it, fills the corresponding sector using the image .IR srcid . The .I thick field is ignored, but must be non-negative. .HP .B f .IR id [4] .br Free the resources associated with the image .IR id . .HP .B F .IR id [4] .br Free the the screen with the specified .IR id . Windows on the screen must be freed separately. .HP .B i .IR id [4] .IR n [4] .IR ascent [1] .br Treat the image .I id as a font cache of .I n character cells, each with ascent .IR ascent . .HP .B l .IR cacheid [4] .IR srcid [4] .IR index [2] .IR r [4*4] .IR sp [2*4] .IR left [1] .IR width [1] .br Load a character into the font cache associated with image .I cacheid at cache position .IR index . The character data is drawn in rectangle .I r of the font cache image and is fetched from the congruent rectangle in image .I srcid with upper left corner .IR sp . .I Width specifies the width of the character\(emthe spacing from this character to the next\(emwhile .I left specifies the horizontal distance from the left side of the character to the left side of the cache image. The dimensions of the image of the character are defined by .IR r . .HP .B L .IR dstid [4] .IR p0 [2*4] .IR p1 [2*4] .IR end0 [4] .IR end1 [4] .IR thick [4] .IR srcid [4] .IR sp [2*4] .br Draw a line of thickness .RI 1+2× thick in image .I dstid from point .I p0 to .IR p1 . The line is drawn using the image .IR srcid , translated so that point .I sp in .I srcid aligns with .I p0 in .IR dstid . The .I end0 and .I end1 fields specify whether the corresponding line end should be a square, a disc, or an arrow head. See .I line in .IR draw-image (2) for more details. .HP .B N .IR id [4] .IR in [1] .IR j [1] .IR name [ j ] .br If .I in is non-zero, associate the image .I id with the string .IR name . If .I in is zero and