Return to ch06b.t CVS log

Up to [CSRG BSD Unix] / 43BSD / contrib / X / doc / Xlib

Annotation of 43BSD/contrib/X/doc/Xlib/ch06b.t, revision 1.1

1.1     ! root        1: .NH 2
        !             2: Line Drawing and Fill Operations
        !             3: .FD
        !             4: .IN "Definitions" "XLine"
        !             5: .IN "XLine"
        !             6: .IN "Line" "Drawing"
        !             7: XLine (w, x1, y1, x2, y2, width, height, pixel, func, planes)
        !             8:        Window w;
        !             9:        int width, height;      /* brush */
        !            10:        int x1, y1, x2, y2;     /* beginning and end points */
        !            11:        int pixel;      /* pixel value */
        !            12:        int func;       /* display function */
        !            13:        int planes;     /* plane mask */
        !            14: .FN
        !            15: \fIXLine\fP draws a line from pixel (\fIx1\fP,\fIy1\fP) to pixel
        !            16: (\fIx2\fP,\fIy2\fP) inclusive
        !            17: in the specified window, using the specified display function \fIfunc\fP.
        !            18: .PP
        !            19: The line will be drawn in the color specified by the \fIpixel\fP value.
        !            20: .PP
        !            21: \fIWidth\fP and \fIheight\fP
        !            22: specify the size of a brush to be drawn along the line.
        !            23: See the description of brushes at the beginning of this section.
        !            24: .PP
        !            25: The plane mask \fIplanes\fP
        !            26: specifies which planes of the display will be modified.
        !            27: .FD
        !            28: .IN "Definitions" "XDraw"
        !            29: .IN "XDraw"
        !            30: .IN "Line" "Drawing"
        !            31: XDraw (w, vlist, vcount, width, height, pixel, func, planes)
        !            32:        Window w;
        !            33:        int vcount;     /* number of vertices */
        !            34:        Vertex *vlist;
        !            35:        int height, width;      /* brush */
        !            36:        int pixel;      /* pixel value */
        !            37:        int func;       /* display function */
        !            38:        int planes;     /* plane mask */
        !            39: .FN
        !            40: \fIXDraw\fP draws an arbitrary polygon or curve using the specified function.
        !            41: The figure drawn is defined by the list of Vertexes \fIvlist\fP
        !            42: that the caller supplies.
        !            43: The points will be connected by lines as specified in the flags
        !            44: in the vertex structure.
        !            45: .PP
        !            46: \fIWidth\fP and \fIheight\fP
        !            47: specify the size of a brush to be drawn along the line.
        !            48: See the description of brushes at the beginning of this section.
        !            49: .PP
        !            50: The plane mask \fIplanes\fP
        !            51: specifies which planes of the display will be modified.
        !            52: .PP
        !            53: .IN "File" "<X/X.h>"
        !            54: Each Vertex is a structure (defined in \fI<X/X.h>\fP):
        !            55: .IN "Data Structures" "Vertex"
        !            56: .IN "Vertex"
        !            57: .nf
        !            58: .sp
        !            59:    typedef struct _Vertex {
        !            60:        short x, y;
        !            61:        unsigned short flags;
        !            62:    } Vertex;
        !            63: .fi
        !            64: .LP
        !            65: \fIX\fP and \fIy\fP are the coordinates of the vertex,
        !            66: relative to either the upper
        !            67: .IN "Vertex" "Flags"
        !            68: left inside corner of the window (if the \fIVertexRelative\fP
        !            69: bit in \fIflags\fP
        !            70:  is 0) or
        !            71: the previous vertex (if \fIVertexRelative\fP is 1).
        !            72: .PP
        !            73: .IN "File" "<X/X.h>"
        !            74: .IN "Vertex" "Flags"
        !            75: The flags, as defined in \fI<X/X.h>\fP, are as follows:
        !            76: .LP
        !            77: .TS
        !            78: center;
        !            79: l c l.
        !            80: VertexRelative 0x0001  else absolute
        !            81: VertexDontDraw 0x0002  else draw
        !            82: VertexCurved   0x0004  else straight
        !            83: VertexStartClosed      0x0008  else not
        !            84: VertexEndClosed        0x0010  else not
        !            85: VertexDrawLastPoint    0x0020  else don't
        !            86: .TE
        !            87: .IN "VertexRelative"
        !            88: \fIVertexRelative\fP is described above.
        !            89: If bit 0 is not set, the coordinates are absolute (relative to the window).
        !            90: The first vertex must be an absolute vertex.
        !            91: .PP
        !            92: .IN "VertexDontDraw"
        !            93: If the \fIVertexDontDraw\fP bit is 1, no line or curve is drawn from the previous
        !            94: vertex to this one.  This is analogous to picking up the pen and moving
        !            95: to another place before drawing another line.
        !            96: .PP
        !            97: .IN "VertexCurved"
        !            98: If the \fIVertexCurved\fP bit is 1, a spline algorithm is used to draw a smooth
        !            99: curve from the previous vertex, through this one, to the next vertex.
        !           100: Otherwise, a straight line is drawn from the previous vertex.
        !           101: It makes
        !           102: sense to set \fIVertexCurved\fP to 1 only if a previous and next vertex are
        !           103: both defined (either explicitly in the array, or through the definition
        !           104: of a closed curve--see below.)
        !           105: .PP
        !           106: It is permissible for \fIVertexDontDraw\fP
        !           107: bits and \fIVertexCurved\fP bits to both be 1; 
        !           108: this is useful if you want to define the `previous point' for the smooth
        !           109: curve, but don't want an actual curve drawing to start until this
        !           110: point.
        !           111: .PP
        !           112: .IN "VertexStartClosed"
        !           113: If \fIVertexStartClosed\fP bit is 1, then this point marks the beginning of a
        !           114: closed curve.  
        !           115: This vertex MUST be followed later in the array by
        !           116: another vertex whose absolute coordinates are identical, and which has
        !           117: .IN "VertexEndClosed"
        !           118: \fIVertexEndClosed\fP bit of 1.
        !           119: The points in between form a cycle for the purpose
        !           120: of determining predecessor and successor vertices for the spline
        !           121: algorithm.
        !           122: It makes sense to set \fIVertexStartClosed\fP bit or \fIVertexEndClosed\fP bit
        !           123: to 1 only if \fIVertexCurved\fP is also 1.
        !           124: .PP
        !           125: Normally, the end point of a curve or line is not drawn, since it is
        !           126: probably the beginning point of the next curve or line.
        !           127: .IN "Display Functions"
        !           128: This is important if
        !           129: a display function such as \fIGXinvert\fP or \fIGXxor\fP
        !           130: is used, since drawing a
        !           131: point twice with such a function produces a different result than
        !           132: drawing it just once.
        !           133: If \fIVertexDrawLastPoint\fP is 1, the end point is drawn.  
        !           134: .PP
        !           135: .PP
        !           136: The line will be drawn in the color specified by the pixel value.
        !           137: .FD
        !           138: .IN "Definitions" "XAppendVertex"
        !           139: .IN "XAppendVertex"
        !           140: int XAppendVertex(vertices,nvert)
        !           141:        Vertex vertices[];
        !           142:        int nvert;
        !           143: .FN
        !           144: This function appends \fIvertices\fP to the output buffer.
        !           145: It is the responsibility of higher level subroutines to determine
        !           146: if the previous draw command was of the same type.
        !           147: This subroutine is NOT intended for normal users of this library,
        !           148: but as a hook for certain libraries built on this library.
        !           149: This function returns a 0 if there is no Draw command currently in
        !           150: the output buffer, -1 if the vertices would not fit before the end of
        !           151: the buffer, or \fInvert\fP if it was successful at appending the vertices.
        !           152: .FD
        !           153: .IN "Definitions" "XClearVertexFlag"
        !           154: .IN "XClearVertexFlag"
        !           155: XClearVertexFlag()
        !           156: .FN
        !           157: This routine clears the state of the flag marking if it is safe to
        !           158: append vertices.
        !           159: Again, this is principally for use of more sophisticated libraries.
        !           160: .sp 2
        !           161: .PP
        !           162: When drawing lines, one may want to draw `dashed' or `dotted' lines.
        !           163: This means you want to be able to some how specify the length of the
        !           164: dashes, and the distance between them.
        !           165: These functions therefore take  a `pattern' specifier.
        !           166: .PP
        !           167: .IN "Macro" "DashedLine"
        !           168: .IN "Macro" "DottedLine"
        !           169: .IN "Macro" "SolidLine"
        !           170: \fIXlib.h\fP has some predefined pattern values (actually macro invocations)
        !           171: of \fIDashedLine\fP, \fIDottedLine\fP,
        !           172: \fISolidLine\fP.
        !           173: .IN "Definitions" "Patterns"
        !           174: .IN "Patterns"
        !           175: Since these predefined patterns are macro invocations and evaluate
        !           176: to an integer,
        !           177: you can use the predefined patterns to initialize static data.
        !           178: .FD
        !           179: .IN "Definitions" "XMakePattern"
        !           180: .IN "XMakePattern"
        !           181: .IN "Patterns"
        !           182: Pattern XMakePattern(pattern, length, multiplier)
        !           183:        int pattern, length, multiplier;
        !           184: .FN
        !           185: In this macro, \fIpattern\fP is a bit string of the specified \fIlength\fP (at
        !           186: most 16 bits).
        !           187: The \fImultiplier\fP specifies how many times each bit in the
        !           188: string should be repeated before moving to the next bit.
        !           189: It cannot be more than 4096.
        !           190: The bits are used least significant bit first, and repeated as many times
        !           191: as needed.
        !           192: .FD
        !           193: .IN "Definitions" "XDrawPatterned"
        !           194: .IN "Definitions" "XDrawDashed"
        !           195: .IN "XDrawPatterned"
        !           196: .IN "XDrawDashed"
        !           197: .IN "Patterns"
        !           198: XDrawPatterned (w, vlist, vcount, width, height, pixel, altpix, pattern, func, planes)
        !           199:        int altpix;
        !           200: 
        !           201: XDrawDashed (w, vlist, vcount, width, height, pixel, pattern, func, planes)
        !           202:        Window w;
        !           203:        int pixel;      /* pixel value */
        !           204:        int height, width;      /* brush size */
        !           205:        int vcount;     /* number of vertices */
        !           206:        Vertex *vlist;
        !           207:        Pattern pattern;        /* pattern specification */
        !           208:        int func;       /* display function */
        !           209:        int planes;     /* plane mask */
        !           210: .FN
        !           211: .IN "XDraw"
        !           212: These functions are similar to \fIXDraw\fP,
        !           213: except they draw a dashed rather than a
        !           214: solid line.
        !           215: The pattern is a value encoding the pattern to be used.
        !           216: .PP
        !           217: For a dashed line, the destination is only updated when the pattern bit
        !           218: is one.
        !           219: .PP
        !           220: For a patterned line,
        !           221: the alternate source pixel value is used when the pattern bit is zero.
        !           222: .FD
        !           223: .IN "Definitions" "XDrawTiled"
        !           224: .IN "Definitions" "XDrawFilled"
        !           225: .IN "XDrawTiled"
        !           226: .IN "XDrawFilled"
        !           227: XDrawTiled (w, vlist, vcount, tile, func, planes)
        !           228:        Pixmap tile;
        !           229: 
        !           230: XDrawFilled (w, vlist, vcount, pixel, func, planes)
        !           231:        Window w;
        !           232:        Vertex *vlist;
        !           233:        int vcount;     /* number of vertices */
        !           234:        int pixel;      /* pixel value */
        !           235:        int func;       /* display function */
        !           236:        int planes;     /* plane mask */
        !           237: .FN
        !           238: .IN "Polygons"
        !           239: \fIXDrawFilled\fP draws arbitrary polygons or curves and fills them with 
        !           240: the specified \fIpixel\fP value.
        !           241: .IN "Filled Polygons"
        !           242: XDrawTiled draws arbitrary polygons or curves and fills them with 
        !           243: the specified \fItile\fP Pixmap.
        !           244: .IN "XDraw"
        !           245: The \fIvlist\fP, \fIvcount\fP, \fIfunc\fP and \fIplanes\fP
        !           246: arguments are identical to \fIXDraw\fP.
        !           247: Note that there may be implementation restrictions on the
        !           248: nature of the \fItile\fP Pixmap.
        !           249: (See \fIXQueryTileShape\fP.)
        !           250: The vertex list should consist only of one or more closed regions.
        !           251: A point is defined to be inside a region if an infinite ray with the point
        !           252: as an origin crosses the path of the region an odd number of times.
        !           253: .IN "XQueryTileShape"
        !           254: .FD
        !           255: .IN "Definitions" "XQueryBrushShape"
        !           256: .IN "XQueryBrushShape"
        !           257: .IN "Limitations" "Brush Shape"
        !           258: XQueryBrushShape (width, height, cwidth, height)
        !           259:        int width, height;
        !           260:        int *cwidth, *cheight;  /* RETURN of `closest' legal size */
        !           261: .FN
        !           262: This function returns the `closest' shape actually supported by the
        !           263: display hardware for brushes, since not all hardware is capable of supporting
        !           264: arbitrary size brushes.
        !           265: Painting lines using brushes of widths not supported by the hardware
        !           266: has unpredictable results.

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.