[Copyright status: this file is in the public domain.]

In a few cases, there is a request to draw multiple similar objects,
but it is convenient from an API perspective to provide a call that
draws one such object, with liblx converting multiple
sufficiently-similar calls to the API routine into a single protocol
request.  An example is single-point drawing.

Xlib does this by, for example, turning multiple XDrawLine calls into a
single PolySegment request, when the XDrawLine calls are sufficiently
similar.  liblx has such a facility, but, in keeping with its
preference for staying close to the protocol, the details differ.

There are five `batching' convenience routines, each of which draws a
single object many of which can be combined into a single protocol
request when they use the same drawable and GC.

Specifically, the routines and the protocol requests:

	lx_draw_line		PolySegment
	lx_draw_point		PolyPoint
	lx_draw_rectangle	PolyRectangle
	lx_fill_arc		PolyFillArc
	lx_fill_rectangle	PolyFillRectangle

This implementation misses some opportunities for batching.  For
example, a CreateWindow request could, in theory, be inserted into a
batch of any of the above calls without harm.  We are conservative in
this regard; any request-generating call that isn't made through these
routines is considered to break batching.  (This includes calls to the
routine underlying the batch; for example, an lx_PolyPoint call will
break a batch of lx_draw_point calls even if it uses the same drawable
and gc as the batch.)

But GC-changing requests also break batches.  The implementation
depends on this; two otherwise batchable calls to, for example,
lx_fill_rectangle, with a GC-changing call affecting the relevant gc in
between, should not be collapsed.

In these calls, the first three arguments are the connection, the
drawable, and the graphics context.  The rest describe the drawable
object in question.  For details, such as exactly what it means to draw
a line from (x1,y1) to (x2,y2), see the corresponding protocol request
(PolySegment in the case of lines).

lx_draw_line
------------

void lx_draw_line(LX_CONN *conn, LX_XID d, LX_XID gc, int x1, int y1, int x2, int y2)

Draws a single line from (x1,y1) to (x2,y2), potentially batching
multiple lines into a single PolySegment request.

lx_draw_point
-------------

void lx_draw_point(LX_CONN *conn, LX_XID d, LX_XID gc, int x, int y)

Draws a single point at (x,y), potentially batching multiple lines into
a single PolyPoint request.

lx_draw_rectangle
-----------------

void lx_draw_rectangle(LX_CONN *conn, LX_XID d, LX_XID gc, int x, int y, int w, int h)

Draws an outlined rectangle, w by h at (x,y), potentially batching
multiple rectangles into a single PolyRectangle request.

lx_fill_arc
-----------

void lx_fill_arc(LX_CONN *conn, LX_XID d, LX_XID gc,
	int x, int y, unsigned int w, unsigned int h, int a1, int a2)

Draws a filled arc with the specified parameters, potentially batching
multiple arcs into a single PolyFillArc request.

lx_fill_rectangle
-----------------

void lx_fill_rectangle(LX_CONN *conn, LX_XID d, LX_XID gc, int x, int y, int w, int h)

Draws a filled rectangle, w by h at (x,y), potentially batching
multiple rectangles into a single PolyFillRectangle request.

lx_end_batch
------------

int lx_end_batch(LX_CONN *conn)

Ends any batch-in-progress.  This is normally not needed, but
occasionally it is useful; for example, if you (say) use lx_draw_line
to draw a line and then have nothing more to do and thus return to the
event loop, then the partial batch will remain buffered.  Almost any
other call will also end the batch; lx_end_batch exists for cases where
you don't have anything else you want to do.  (Calls that don't end
batches are marked as such in their documentation - or at least are
supposed to be.)

If no batch is in progress for conn, this call is very cheap.

It returns nonzero if it did anything, zero if it found there was
nothing for it to do (ie, no batch was in progress).

----

There is no batching routine backed by PolyArc requests, for the same
reason there is no batching routine backed by PolyLine requests: joins
between adjacent objects.  Or, to put it another way, there is no
lx_draw_arc because there is no protocol request that is to PolyArc
what PolySegment is to PolyLine.

Arguably, lx_draw_arc should exist as a convenience routine, one which
just turns into a single-arc PolyArc request.  I may do such things
someday.