Pen Object Library: 1.2 The Ink Object: Storing Ink to DB Items

Pen information comes in as a MSG_META_NOTIFY_WITH_DATA_BLOCK of type NT_INK accompanied by an array containing the coordinates visited by the pen. The pen data keeps track of the coordinates of the pen input. Every time pen input comes in, the ink object notes the coordinates. The ink object is optimized to save space. For instance, the Ink object eliminates collinear points: if three pen events are collinear, it will not record the middle one, recognizing it as redundant.

The non-redundant points are written out to the II_segments field, a chunk array of Point structures. Note that the coordinates are unsigned. If a point's x coordinate's sign bit is set, that does not mean that the x coordinate is negative; if this sign bit is set this is a signal that this point is the last point of a gesture.

When writing pen data to a DB item, the Ink object does some more compression. Applications which work with the items used by MSG_INK_SAVE_TO_DB_ITEM and MSG_INK_LOAD_FROM_DB_ITEM must work with this compression. Since the user is dragging the pen around in a continuous gesture, the pen events tend to occur close together. Thus, it is nice to have a way to record a coordinate as a small offset from another coordinate. Since many strokes are almost horizontal or vertical, quite often the horizontal or vertical offset will be zero or one.

To take advantage of these tendencies, the ink object stores pen input as a bitstream. Coordinates may be recorded either as absolute positions or as offsets from the last coordinate.

When writing out a gesture to a DB item, the first point will always be recorded as an absolute position. Thus, first the x coordinate will be recorded, then the y coordinate. Each coordinate will be marked as absolute by the 1011 bit pattern.

For each subsequent pen point, the algorithm will first make sure that the new point is not collinear with the previous two. If it is, then the algorithm will make the incoming pen event overwrite the previous event's coordinates.

For each event, the algorithm will first write out the x coordinate, then the y coordinate.

If the coordinate is at 0 or 1 offset from the previous coordinate, the algorithm will write out the appropriate two-bit code (00, 01, or 11).
If the coordinate is at an offset from the previous coordinate between 2 and 8, then the algorithm will write out the appropriate 7 bit code (1000xxx for a positive offset, 1001xxx for a negative offset).
If the coordinate is more than 8 points from the previous coordinate, the algorithm writes out 1011 followed by the absolute coordinate, represented as a 15 bit unsigned quantity.

When the input is finished, the algorithm writes a 1000000 bit pattern, signalling the end of the segment.

Decompressing the data is a matter of traversing the bitstream and detecting the appropriate patterns.

As an example of how the algorithm compresses pen input, suppose the Ink object were writing the following gesture to a DB item:

(72, 71)
(82, 74)
(84, 74)
(85, 72)

The first coordinate is 72, so the algorithm will write out:
1011 (signals absolute coordinate) 000000001001000
The second coordinate is 71, so after handling the second coordinate, the stream will be:
1011 000000001001000 1011 000000001000111
The x coordinate of the second point is 82, which is 10 points away from the previous x coordinate. Unfortunately, this is too far to express as a short offset, so the algorithm writes another absolute coordinate (the new part of the stream is shown in italics):
1011 000000001001000 1011 000000001000111 1011 000000001010010
The y coordinate of the second point is 74, at a positive 3 offset from the previous y value, so the algorithm will write out the appropriate offset code instead of an absolute position code:
...1011 000000001000111 1011 000000001010010 10 00 010
The third point's x coordinate is 84, at a +2 offset from 82. The y coordinate is 74, the same as the previous point's y coordinate:
...1011 000000001000111 1011 000000001010010 10 00 010 10 00 001 00
The last point's x coordinate is one higher than the previous; its y coordinate is two less.
...1011 000000001010010 10 00 010 10 00 001 00 01 10 01 001
Since it has reached the end of the pen input (this was a suspiciously short gesture, a somewhat contrived example), the algorithm then writes an end-of-segment code:
...1011 000000001010010 10 00 010 10 00 001 00 01 10 01 001 10 00 000
If the Ink object were holding more than one gesture of information, it would write the next gesture's elements starting after the end-of-segment code of the first.

GEOS SDK TechDocs |

1.1 Instance Data and Messages | Next:

2 Working with the Ink DB