Site logo

 

Introduction

The Clock Interchange File Format (CIFF, extension .ciff) is a file format created to build clock designs in an easy way for portable electronic devices or embedded systems.

The main idea behind the design was to allow anyone with an image editor and a text editor to be able to create any sort of custom clock for a handheld electronic device like a smartphone or an iPod, or an embedded system. The format defines a straight forward image layering system to allow for a very simple implementation on the viewer application, specially thought for embedded systems.

A CIFF file is only the definition of a clock structure and must be included with the image files that make up each image layer of the clock.

Since the file format readers are intended to be very simple the file format has some rules that must be followed strictly.

Format Description

The first line is always:
# CIFF
This defines the file as a CIFF file.
Any line starting with the # character is treated as a comment and ignored until the end of the line.
All content is case insensitive, but using uppercase is preferred.

Basic rules
  • Clocks are defined by a set of parameter lines.
  • Each line starts with a letter that identifies the line's contents.
  • Each parameter on the line is separated by a semicolon.
  • No blank spaces are allowed on the line unless they are part of an image's filename.
  • The order of the lines defines the order of the layers. The first line will be rendered first (bottom of the layer stack) and will usually be the background image.

Clock canvas details
By default the CIFF file is assumed to be created for the device's native resolution and a default black background color. This can be changed with the following line:
B;SizeX;SizeY;Red;Green;Blue

B:
SizeX, SizeY:
Red, Green, Blue:
Example:

Identifies this is the base image description line.
Base horizontal and vertical resolution of the design in pixels.
Color components of the default background color used to fill in empty areas, in values from 0.0 to 1.0.
B;640;960;1;0;0 (iPhone Retina display size with default red background)
When a clock is rendered on a device that has different dimensions than the specified base size, the rendering will be centered on the screen and the clock size adjusted to fit completely, but respecting the original aspect ratio.

Important: This line must appear before any layer lines, otherwise it will be ignored.

Clock layers
The clock contents are defined by three types of image layers:
  • Static images, which never move.
  • Analog images, which can be defined to rotate with time (like a clock hand).
  • Digital images, that will be switched with time (like digital clock digits).

A clock definition can have any number of these layers and in any order. Each line is considered a layer and the rendering order of the layers is based on the order on which their parameter lines are present on the file.

If any line is missing a parameter or the values are out of range, that line is ignored.
All coordinates are based on a top-left to bottom-right coordinate system.

Layer images can be in JPEG or PNG format.

Time types
The time types are what defines the values that each layer displays or moves by. They are all two character codes and must be used in the TimeType parameter of a layer.
  • Y4: Year in 4 digits
  • Y2: Year last 2 digits
  • MN: Month
  • DY: Day
  • WD: Day of week (starting on Sunday = 1)
  • HH: Hour 00-23
  • GG: Hour 00-11 (for 12 hour clocks, like analog or AM/PM)
  • AP: AM = 0, PM = 1
  • MM: Minute 00-59
  • SS: Second 00-59

Static image layer

S;Filename;AnchorX;AnchorY;PositionX;PositionY

Filename:
AnchorX, AnchorY:
PositionX, PositionY:

Example:

Image file for the layer.
Image coordinates of image location that will be place at PositionX, PositionY.
Canvas coordinates where the image's anchor point will be placed.

S;image.png;0;0;100;50

Analog image layer

The image on this layer will be rotated around its anchor point at the time interval specified.
The image must be at the 12 o'clock position.
A;Filename;AnchorX;AnchorY;PositionX;PositionY;TimeType;Smooth

Filename:
AnchorX, AnchorY:
PositionX, PositionY:

TimeType:
Smooth:


Example:

Image file for the layer.
Coordinates of the rotation center of the image.
Canvas coordinates where the image rotation center defined by (AnchorX, AnchorY) will be placed.
Time type that controls this layer as specified above.
Y if you want the needles to rotate in a smooth way between values or N if you want them to jump.

A;needle.png;20;80;200;200;GG;N

Digital image layer

The image for this layer must contain the image tiles for each of these numbers and symbols in this exact same order:
- . / 0 1 2 3 4 5 6 7 8 9 :
Each tile must have the same width.
Some tiles may be left blank if you are sure that those characters will not be used.
D;Filename;AnchorX;AnchorY;PositionX;PositionY;TimeType;LeadingZeros;CharacterWidth

Filename:
AnchorX, AnchorY:
PositionX, PositionY:
LeadingZeros:
CharacterWidth:

Example:

Image file for the layer.
Image coordinates of image location that will be place at PositionX, PositionY.
Canvas coordinates where the digital characters image's anchor point will be placed.
Y if you want to display double digit values as two digits regardless of their value.
The width of the characters in the digital image layer.

D;digitalnumbers.png;0;0;100;50;HH;Y;20

Sample file

# This file would define a simple clock with a background image containing all
# the static imagery and two needle images for hours and minutes.

# Base device size
B;640;960;1;0;0

# Background clock image
S;background.png;0;0

# Analog needles
A;needle1.png;10;60;200;200;GG;N
A;needle2.png;20;80;200;200;MM;N