{"id":260,"date":"2016-12-20T00:01:21","date_gmt":"2016-12-20T00:01:21","guid":{"rendered":"http:\/\/www.piboxproject.com\/?p=260"},"modified":"2016-12-20T00:01:21","modified_gmt":"2016-12-20T00:01:21","slug":"pibox-piclock-themes-using-cairo","status":"publish","type":"post","link":"https:\/\/www.piboxproject.com\/index.php\/2016\/12\/20\/pibox-piclock-themes-using-cairo\/","title":{"rendered":"PiBox: PiClock themes using Cairo"},"content":{"rendered":"
<\/a>

The original clock was primitive, mostly because I didn’t understand how to use images and transformations correctly, even though I’d used them in the PiBox launcher!<\/p><\/div>\n

Having just completed work on a wifi scanner for PiBox Network Config<\/a>, I decided to expand on the lessons learned with Cairo to add themes to PiClock<\/a>.\u00a0 The original clock was a simple drawing of the clock face boundary with three hands.\u00a0 The biggest task there was to compute the end points of the lines drawn for each hand.\u00a0 Nothing complex there.<\/p>\n

But there is no reason custom clock face images and hands can’t be used.\u00a0 The trick is learning to work with Cairo<\/a> layers (which happens without extra coding) and discovering how to properly rotate and position the hands.\u00a0 Turns out none of this is hard, but it was hard finding out how to use the Cairo API.<\/p>\n

So the first thing to do for a theme is define what I wanted to display.\u00a0 There are five images you define for PiClock themes:\u00a0 the clock face<\/em>, the hour<\/em>, minute<\/em> and second<\/em> hands and an overlay<\/em> image.\u00a0 The overlay allows you to add special effects like a glass cover.\u00a0 The theme needs a configuration file to specify these images.\u00a0 I chose to use a JSON<\/a> format.\u00a0 Previously, PiBox apps used XML for configuration files but in the last year I’ve become a big fan of JSON due to its easy-to-read name\/value pair format.\u00a0 Also, I’ve found a very simple to use and lightweight JSON library called Parson<\/a>.\u00a0 I’ve integrated this into libpibox<\/a> so all apps can use it.<\/p>\n

The JSON format for PiClock themes is extremely simple.<\/p>\n

{ <\/code>
\n\u00a0\u00a0\u00a0\u00a0 \"theme\": {<\/code>
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 \"face\":\"<Name of clock face file>\",<\/code>
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 \"overlay\":\"<Name of clock overlay file>\",<\/code>
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 \"hour\":\"<Name of hour hand file>\",<\/code>
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 \"min\":\"<Name of minute hand file>\",<\/code>
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 \"sec\":\"<Name of second hand file>\",<\/code>
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 \"center\":{<\/code>
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 \"hour\": { \"x\":n, \"y\":m },<\/code>
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 \"min\": { \"x\":n, \"y\":m },<\/code>
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 \"sec\": { \"x\":n, \"y\":m }<\/code>
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 },<\/code>
\n\u00a0\u00a0\u00a0\u00a0 } <\/code>
\n}<\/code><\/p>\n

The clock face has a dimension limit of 512×512 which the code enforces.\u00a0 After experimentation on the PiBox hardware I found it was best to make faces at that size and not smaller, but I don’t enforce that.\u00a0 The center object defines the rotation point within each of the hands images as it cannot be assumed the hand rotates around its real center.\u00a0 Other than that, the theme is self explanatory.<\/p>\n

Before I could parse the file I needed it to have a home.\u00a0 I use the -T option when testing PiBox apps which points the code at files within the source tree.\u00a0 In production the data files are stored under \/etc\/piclock\/themes.\u00a0 Since there can be more than one theme there needs to be a top level file stating the currently selected theme.<\/p>\n

Parsing the file requires a single line of Parson code, plus extracting a reference to access fields.<\/p>\n

JSON_Value data = json_parse_file_with_comments(buf);<\/code>
\nobj = json_value_get_object(data);<\/code><\/p>\n

The data object is abstract.\u00a0 Fields can be extracted rather easily using the dot<\/em> functions:<\/p>\n

face = json_object_dotget_string(obj, \"theme.face\");<\/code>
\n hour = json_object_dotget_string(obj, \"theme.hour\");<\/code>
\n min = json_object_dotget_string(obj, \"theme.min\");<\/code>
\n sec = json_object_dotget_string(obj, \"theme.sec\");<\/code>
\n overlay = json_object_dotget_string(obj, \"theme.overlay\");<\/code><\/p>\n

This extracts the filenames, which must be prefixed with the installation directory.\u00a0 Following this is an in depth evaluation of the configuration to make sure files exist, can be read into Cairo surfaces and have reasonable sizes with centers properly defined.<\/p>\n

A clock theme is drawn by first drawing a black background (for any transparent regions in the images).\u00a0 The clock face is drawn over this.\u00a0 The surfaces for the face and hands are generated when the theme is read so that they can be reused every time the clock is updated.\u00a0 The hands are drawn over the face and the overlay over the hands.\u00a0 Those are the layers.\u00a0 As long as they are drawn in this order the layers are composited correctly.<\/p>\n

Now for the important trick:\u00a0 translation and rotation.\u00a0 What was difficult to discover the use of patterns and matrices<\/a> for the drawing operation.\u00a0 The pattern is effectively a copy of the original image surface.\u00a0 The pattern is first translated so its defined center is at the origin (0,0) at which point the rotation is applied.\u00a0 Then the pattern is moved to the center of the clock window.\u00a0 Obviously the face and overlay don’t need rotations, just the hands.\u00a0 Here is the generic handler for hands.<\/p>\n

void draw_hand(GtkWidget *widget, cairo_t *cr, gint hand)
\n{
\ncairo_status_t\u00a0 rc;
\ncairo_surface_t *image = NULL;
\ncairo_pattern_t *pattern;
\ngint\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 width, height;
\ngdouble\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 offset_x, offset_y;
\nGtkPiclock\u00a0\u00a0\u00a0\u00a0\u00a0 *piclock;
\nGtkRequisition\u00a0 req;
\ncairo_matrix_t\u00a0 matrix;<\/code><\/p>\n

\u00a0\u00a0\u00a0 piclock = GTK_PICLOCK(widget);<\/code>
\n \u00a0\u00a0\u00a0 req.width = gdk_window_get_width(widget->window);<\/code>
\n \u00a0\u00a0\u00a0 req.height = gdk_window_get_height(widget->window);<\/code><\/p>\n

\u00a0\u00a0\u00a0 \/*
\n* Setup based on the hand requested.
\n*\/
\nswitch( hand )
\n{
\ncase HAND_HOUR:
\nimage = piclock->theme->hour_sf;
\ndegrees = -1*(double)piclock->hoursHand\/60.0*360.0;
\noffset_x = (double)piclock->theme->hour_pt.x;
\noffset_y = (double)piclock->theme->hour_pt.y;
\nbreak;
\ncase HAND_MIN:
\nimage = piclock->theme->min_sf;
\ndegrees = -1*(double)piclock->minutesHand\/60.0*360.0;
\noffset_x = (double)piclock->theme->min_pt.x;
\noffset_y = (double)piclock->theme->min_pt.y;
\nbreak;
\ncase HAND_SEC:
\nimage = piclock->theme->sec_sf;
\ndegrees = -1*(double)piclock->secondsHand\/60.0*360.0;
\noffset_x = (double)piclock->theme->sec_pt.x;
\noffset_y = (double)piclock->theme->sec_pt.y;
\nbreak;
\n}
\nif ( image == NULL )
\nreturn;<\/code><\/p>\n

\u00a0\u00a0\u00a0 width = cairo_image_surface_get_width(image);
\nheight = cairo_image_surface_get_height(image);
\npattern = cairo_pattern_create_for_surface (image);<\/code><\/p>\n

\u00a0\u00a0\u00a0 \/* translate the rotation point of the hand to the origin. *\/<\/code>
\n \u00a0\u00a0\u00a0 cairo_matrix_init_identity (&matrix);<\/code>
\n \u00a0\u00a0\u00a0 cairo_matrix_translate (&matrix, (double)offset_x, (double)offset_y);<\/code><\/p>\n

\u00a0\u00a0\u00a0 \/* Rotate to the correct clock position. *\/<\/code>
\n \u00a0\u00a0\u00a0 cairo_matrix_rotate (&matrix, deg2rad(degrees));<\/code><\/p>\n

\u00a0\u00a0\u00a0 \/* Move to the center of the clock window *\/<\/code>
\n \u00a0\u00a0\u00a0 cairo_matrix_translate (&matrix,<\/code>
\n \u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 -req.width\/2,<\/code>
\n \u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 -req.height\/2);<\/code>
\n \u00a0\u00a0\u00a0 cairo_pattern_set_matrix (pattern, &matrix);<\/code><\/p>\n

\u00a0\u00a0\u00a0 cairo_set_source (cr, pattern);<\/code>
\n \u00a0\u00a0\u00a0 cairo_pattern_destroy (pattern);<\/code>
\n \u00a0\u00a0\u00a0 cairo_paint(cr);<\/code>
\n }<\/code><\/p>\n

<\/a>

The test theme has a reflective overlay appliedover the face and hands.<\/p><\/div>\n

After getting the window dimensions and accessing the previously created image surface, a pattern is created and a matrix initialized.\u00a0 Then the translation is done to move the configured center point to the origin.\u00a0 A rotation is applied and the pattern is moved to the center of the window.\u00a0 Once the pattern is set as a source for the main Cairo surface it can be destroyed and the main surface updated.<\/p>\n

There are now two themes for PiClock.\u00a0 The first is a test theme that includes the overlay.\u00a0 This isn’t as clean as I’d like – the overlay doesn’t quite look like a reflective surface to me.\u00a0 The overlay is made from a couple of white to transparent radial gradients made with GIMP<\/a>.\u00a0 Cairo composites transparency quite nicely, as can be seen with the clock hands.<\/p>\n

Once the test theme was working I had to make one more theme, to prove that the design worked in general.\u00a0 So I created the roman theme, which is simply an old clock face with roman numerals.\u00a0 The hands were run through GIMP a few times to clean them up and remove colored areas around the hands that were an artifact of the poor original image.<\/p>\n

<\/a>

The roman theme doesn’t use an overlay, but the overlay image is required because I didn’t go to the length of allowing it to be optional. The the image is simply the size of the clock face image but is completely transparent.<\/p><\/div>\n

The theme design worked perfectly on the second theme.\u00a0 I created it to spec and updated the default theme name, then ran PiClock.\u00a0 It displayed as shown.\u00a0 No code changes were required.\u00a0\u00a0 I’ve got some videos of the clocks running, if anyone is interested in watching a clock ticking.<\/p>\n