# remote HID protocol, high level

## reference

### ver(protver)

Sends the protocol version the server will speak. If the client doesn't support that version, it should break the connection.

Arguments:

- protver: an integer value; 1 for the current version

### unit(abbrev)

Sends the coordinate unit used in subsequent communication. This is not necessarily the unit used for displaying values on the user interface, but the unit used to interpret numeric coordinate values sent in commands.

Arguments:

- abbrev: unit name abbreviation; e.g. mm or nm or mil

### ready()

Informs the client that the server is ready to start the session. The client needs to answer with a Ready() message before the server proceeds.

Arguments: none.

### brddim(w h)

Announce board dimensions. Some layers may extend beyond the board.

Arguments:

- w: width (x size) in coordinate units
- h: height (y size) in coordinate units

### inval(x1 x2 y1 y2)

Invalidate a rectangular section of the screen; the client should redraw this area. Clients implementing their own mechanism to keep track on drawing are free to ignore these requests

Arguments:

- x1: left coordinate
- x2: right coordinate
- y1: top coordinate
- y2: bottom coordinate

### inval()

Same as inval(x1 x2 y1 y2) but invalidates the whole screen.

Arguments: none

### newlg(name group_id flags)

Create a new layer group.

Arguments:

- name: name of the layer group - names are not unique
- group_id: unique group ID (decimal integer, may be large)
- flags: a list of 3 items: location, purpose and properties. Each item is a list of values (or an empty list).

Example:

    newlg(topassembly 16777219 ((top) (assy) (virtual)))

Creates the top assembly virtual layer with ID 16777219 with the name of "topassembly"

### newly(name layer_id group_id)

Create a new layer within an existing layer group.

Arguments:

- name: name of the layer (can be empty, not unique)
- layer_id: unique ID of this layer (decimal integer, may be large)
- group_id: reference to a previously created layer group which this layer is part of

Example:

    newly(soldergnd 3 11)

Creates a layer 3 called "soldergnd" in group 11.

### setlg(group_id is_empty purpose)

Inform the client that the next set of drawing commands are for a specific layer group. (Note: the reason for announcing groups and not layers: all layers in that group are drawn at once; visibility of layers within the same group are switched together.)

Arguments:

- group_id: unique ID of the layer group
- is_empty: 1 if the layer group may be empty, 0 if the layer is not empty (TODO: this bit is not 100% reliable yet)
- purpose: layer group purpose field (usefil in mech/doc groups)

### makeGC()

Request the client to make a new graphical context. The client should allocate a GC and return an integer ID using the MadeGC(ID) message. The ID uniquely identifies the GC; it should be small positive integer (between 0 and 31 for now).

Arguments: none

### delGC(ID)

Inform the client that a given GC is not needed anymore. The server will not reference the GC again and the GC can be destroyed (but graphics drawn on the screen should not be affected). The ID may be reused by the client in a subsequent madeGC() message).

Arguments:

- ID: integer ID of the GC

### clr(gci colorstring)

Change the color subsequent drawing commands of a given GC will use.

Arguments:

- gci: ID of the GC
- colorstring: name of the color, specified in the usual "web" format: #rrggbb (with 3 hex numbers)

### cap(gci style)

Set the line ending cap style. Note: the cap extends half-line-width beyond the end coordinates, e.g. the end point of a line is the center of the round-cap circle.

Arguments:

- gci: ID of the GC
- style: r for round cap (circle), s for square cap, b for beveled (octagon)

### linwid(gci width)

Sets line width (pen tip diameter).

Arguments:

- gci: ID of the GC
- width: diameter of the circular aperture of the pen in coord units

### setxor(gci state)

Sets whether to perform "xor-drawing" for subsequent drawing commands in the selected GC.

Arguments:

- gci: ID of the GC
- xor: 0 means normal drawing, 1 means xor drawing

### line(gci x1 y1 x2 y2)

Draw a line using the current GC. The line inherits line width, color and cap style from the GC.

Arguments:

- gci: ID of the GC
- x1: 1st endpoint's X coord (in coord units)
- y1: 1st endpoint's Y coord (in coord units)
- x2: 2nd endpoint's X coord (in coord units)
- y2: 2nd endpoint's Y coord (in coord units)

### rect(gci x1 y1 x2 y2 filled)

Draw a rectangle. The rectangle inherits only color from the GC.

Arguments:

- gci: ID of the GC
- x1: 1st corner X coord (in coord units); x1 <= x2
- y1: 1st corner Y coord (in coord units); y1 <= y2
- x2: 2nd corner X coord (in coord units)
- y2: 2nd corner Y coord (in coord units)
- filled: 1 if the rectangle should be filled; a non-filled rectangle is a frame of 1 pixel wide lines

### fcirc(gci cx cy r)

Draw a filled circle. The circle inherits only color from the GC.

Arguments:

- gci: ID of the GC
- cx1: center X coord (in coord units)
- cy1: center Y coord (in coord units)
- r: radius (in coord units)

### poly(gci len ptlist)

Draw a filled polygon. The polygon inherits only color from the GC.

Arguments:

- gci: ID of the GC
- len: number of contour points
- ptlist: an ordered list of (x y) coordinates (all in coord units)

### umask(m)

"use mask" m. The server uses this message to make an announcement before it starts drawing certain things.

Arguments:

- m: mask name:
  - off: flush the buffer and return to non-mask operation.
  - before: Polygons being drawn before clears.
  - clear: Clearances being drawn.
  - after: Polygons being drawn after clears.