Extensions:Uni-Verse/vclock

Introduction

This page describes the tool called "vclock". The purpose of vclock is to create a "live" bitmap, holding a digital clock. The program updates the clock once a second, so that the displayed clock keeps track of time.

Installation

Currently, vclock is not included in any binary distribution of Verse. Thus, to obtain it, you will need to check out its source code from CVS, and compile it yourself. It should be easy enough to build in Linux and similar environments, but has not been built under Windows yet.

You will find vclock in its own module in the main Verse CVS repository. Check it out from there, enter the resulting directory, and type make.

Requirements

Being very small and quickly developed, vclock has no external dependencies except for Verse itself.

The LED-display-like font is compiled into the program, to change it you need to edit the XPM source file. The code assumes that the font image holds the digits 0..9, in that order left to right. The default image is 320x48 pixels, making each digit 32x48. Please note that the XPM file is a pixmap, so it defines colors as RGB triplets. However, the vclock client treats it as monochrome grayscale, and only uses the red part of each color. Still, it is not a bitmap, since there is the ability to support any number of intensity levels in the single channel.

Running vclock

The vclock program is a pure command-line tool, meaning it has no graphical (window-based) user interface. To use it, you simply run the executable ("binary") from the command prompt, and control its behavior by passing suitable arguments.

The simplest possible invocation looks like this:

 $ vclock

The above will connect to a Verse server on localhost, create the required bitmap node, and start displaying the current time, in the opinion of the machine where vclock is running.

If you want to create a clock on a Verse server running elsewhere, use the -ip option, like so:

 $ vclock -ip=verse.example.org

The above will create a clock on a Verse server running on the host verse.example.org.

Options

Being a command-line only tool, vclock has a number of options you can use to control the way it operates. All options are case-sensitive. Multiple single-letter options cannot be given with a single dash.

These are the supported options (a word enclosed in square brackets denotes an optional part):

-ip=HOST[:PORT]

Specify the host name (or IP address) of the server to which the vclock client should connect.

-border=n

Make the client add n tiles of black border around the clock. This expands the image's total area by VN_B_TILE_SIZE*(2*n)*VN_B_TILE_SIZE*(2*n) pixels. Here, VN_B_TILE_SIZE is an internal Verse constant, the value of which is typically eight.

-layers=[r][g][b][a]

Select which bitmap layers are to be created and then written to by the vclock client. This controls the color of the clock, and let's you select any of the seven primary colors. In theory it is also possible to create an empty clock, although doing so is kind of pointless. The following table summarizes which layer gets created by each of the four letters:

Letter	Layer	Content
r	color_r	Red component of bitmap's color.
g	color_g	Green component of bitmap's color.
b	color_b	Blue component of bitmap's color.
a	alpha	Alpha channel for the bitmap.

-utc

Makes the current time UTC, rather than local. Handy when you want to set up a foreign timezone, which might be specified relative to UTC.

-offset=n

Create a clock that shows the current time, plus n minutes. The offset can be negative.

-node=NAME

Rather than creating its own bitmap node, make the client wait for a node named NAME to show up, and use it. This works best if that node was previously created by an instance of vclock. Not too much care is taken to ensure that the proper layers exist, in this mode.

-wait=n

When waiting for a node using the -name option, this sets the maximum time to wait to n seconds. After the delay has expired, vclock will create the named node itself.

-F

Don't try to be smart when updating the clock, but always send all tiles that make up the clock. If not given, vclock will only send bitmap tiles for the digits that have actually changed. Note that even in the default mode, it is not smart enough to look at the actual tiles' contents: all tiles for a changing digit will be sent.

-C

Create all RGB layers, but only update those specified by the -layers option. This is useful to trick broken clients, that don't otherwise properly interpret the bitmap node.

-h

Prints help text, with summary descriptions of all the options.

Output

The default output from vclock, in the form of a bitmap node created and updated on the indicated Verse server, looks like this:

Here is how the clock looks when running with -border=3 and -layers=r:

As you can see, this results in a red clock, with 3*8=24 pixels of black border all around. The border pixels are never written to.

Limitations

There's no flashing colons ... :)