1845 lines
77 KiB
C
1845 lines
77 KiB
C
/*--------------------------------------------------------------------------
|
|
** File: inkstore.h
|
|
**
|
|
** Copyright 1993, Slate Corporation, All Rights Reserved.
|
|
**
|
|
** This document is part of the Jot specification for the storage and
|
|
** interchange of electronic ink data. This specification is the joint work
|
|
** of representatives of Slate Corporation, Lotus Development Corporation,
|
|
** GO, Microsoft, Apple, General Magic, and others.
|
|
**
|
|
** This document and the accompanying code samples on disk comprise Version
|
|
** 1.0 of the Jot specification for the storage and interchange of electronic
|
|
** ink data. Permission is granted to incorporate and otherwise use any
|
|
** portion of the specification. You may make copies of the specification
|
|
** for distribution to others, provided you include the notice "Copyright
|
|
** 1993, Slate Corporation. All Rights Reserved" on both the document and
|
|
** the disk label. You may not modify this specification without written
|
|
** permission from Slate Corporation.
|
|
**
|
|
** The specification is provided "as is" without warranty of any kind. Slate
|
|
** further disclaims all implied warranties of merchantability or of fitness
|
|
** for a particular purpose. The entire risk arising out of the use or
|
|
** performance of the specification remains with you.
|
|
**
|
|
**--------------------------------------------------------------------------
|
|
**
|
|
** This is the main body of definitions for the ink storage specification.
|
|
** See reference section 1.0 for revision history.
|
|
**
|
|
**------------------------------------------------------------------------*/
|
|
|
|
#ifndef INKSTORE_INCLUDED
|
|
#define INKSTORE_INCLUDED
|
|
|
|
|
|
|
|
|
|
/*************************/
|
|
/* REFERENCE SECTION 0.0 */
|
|
/*************************/
|
|
|
|
/*--------------------------------------------------------------------------
|
|
** "Rationale for the ink specification"
|
|
**
|
|
** This document defines a storage and interchange format for embedded ink
|
|
** data. The format is device- and platform-independent. The goal is to
|
|
** provide application programs on the same and different platforms and
|
|
** operating systems a way to store and exchange ink data. Thus a PenPoint
|
|
** user might scribble a note and send the untranslated ink as part of an
|
|
** e-mail message to a colleague's pen computer running Windows for Pen
|
|
** Computing using Magic Mail.
|
|
**
|
|
** This specification is for a publicly-defined, external format for
|
|
** electronic ink data interchange, and neither assumes nor dictates the
|
|
** nature of how the application deals with ink data internally. The format
|
|
** is not intended to be the "internal" ink format of an application, though
|
|
** there is no reason why it could not serve such a purpose.
|
|
**
|
|
** The scope and goals of this format design are limited to the represent-
|
|
** ation of electronic ink data embedded in some other electronic document,
|
|
** not to the larger document itself (such as an e-mail or enhanced word-
|
|
** processing data file).
|
|
**
|
|
** The approach taken is to capture the complete user input for the
|
|
** electronic ink, including not just X/Y coordinates, but also a large set
|
|
** of current drawing attributes such as nib type and ink color. This
|
|
** differs from other possible approaches, such as those based on certain
|
|
** recognition models for handwritten text, which require decomposing the
|
|
** handwritten ink data first into a set of pre-defined approximation curves
|
|
** or sub-strokes, and then storing a list of encodings of these sub-strokes.
|
|
** In other words, Jot preserves all information about the original input as
|
|
** opposed attempting any sort of abstract characterization of the input.
|
|
**
|
|
** The storage format has a number of properties:
|
|
**
|
|
** * Simple. Typical operations on the ink data are easy. If you only wish
|
|
** to read stroke coordinates and bounding information from the data,
|
|
** complex information that might be present will not hinder the process.
|
|
** Likewise, it is easy to write out just simple information. The
|
|
** complex information is all optional.
|
|
**
|
|
** * Compact. The storage format is intended to be as compact as possible
|
|
** without sacrificing simplicity or fidelity. Optional information such
|
|
** as time stamps or color specifications occupy space only when they are
|
|
** present. Specifications that apply to many strokes (such as line width
|
|
** or color) are represented just once.
|
|
**
|
|
** * Compression. The stroke information that describes the ink can
|
|
** optionally be represented in a compressed format. Compression
|
|
** techniques include both compression and reduction of the ink data.
|
|
**
|
|
** * Inclusive. The format is capable of storing every property of ink
|
|
** conceivable as of today.
|
|
**
|
|
** * Expandable and Compatible. The format is expandable, so as developers
|
|
** discover new information that should be recorded in an ink storage
|
|
** format, these new features can be added without changing the behavior of
|
|
** existing application programs working with an older version of the
|
|
** format. In general, new features can generally be ignored by
|
|
** applications reading older versions of the format. Likewise, new
|
|
** application programs can handle previous versions of the format without
|
|
** special work.
|
|
**
|
|
** The format is not designed to easily support lots of in-memory
|
|
** manipulation of the ink data, such as deleting strokes, changing line
|
|
** widths, and so on. A format supporting these types of manipulations would
|
|
** be at odds with the above goals. All the information needed to perform
|
|
** these manipulations is present in this data format, so an application
|
|
** might augment this format to facilitate manipulation of the ink data.
|
|
**
|
|
** Applications are likely to use some other format internally for real-time
|
|
** ink manipulation. Many operating environments provide some internal means
|
|
** for storing and manipulating ink data, the details of which may be hidden
|
|
** to some extent from the application designer. Many such real-time data
|
|
** structures store fewer types of and/or less information (such as not
|
|
** preserving information about the tablet point data rate) than are covered
|
|
** in this definition.
|
|
**
|
|
**------------------------------------------------------------------------*/
|
|
|
|
|
|
|
|
|
|
/*************************/
|
|
/* REFERENCE SECTION 1.0 */
|
|
/*************************/
|
|
|
|
/*-------------------------------------------------------------------------
|
|
** Jot Ink Specification
|
|
** ---------------------
|
|
**
|
|
** Revision History:
|
|
**
|
|
** March 16, 1992 - First public draft.
|
|
** July 13, 1992 - Major rewrite to put data into a series of records.
|
|
** July 19, 1992 - Inclusion of ink-compacting definitions.
|
|
** July 30, 1992 - Change of target rect to offset.
|
|
** December 28, 1992 - Changes incorporated from August 1992 review meeting.
|
|
** February 12, 1993 - Incremental fixes due to coding experience.
|
|
** March 13, 1993 - Revised definition of a "group".
|
|
** April 12, 1993 - Release of version 0.99 of the specification. Moved
|
|
** reference sections 28 and 29 to a separate file called
|
|
** sample.h
|
|
** May 01, 1993 - Release of version 1.00 of the specification.
|
|
** Changed INK_OFFSET_RECORD units from twips to pen
|
|
** units for consistency and ease of implementation.
|
|
** Fixed a typo in reference section 26.0 in the diagram.
|
|
** The text accompanying the diagram was correct.
|
|
** Fixed a typo in reference section 27.0. The old text
|
|
** "delta-X == 0 or 1" was replaced with the correct text
|
|
** "delta-X == 2". The accompanying diagram was correct.
|
|
** Removed all sizeof() constructs and replaced with
|
|
** appropriate #defines to reduce compiler dependencies.
|
|
** Tagged all struct definitions with tag_ prefix.
|
|
** Added comments and reordered some existing comments.
|
|
** May 17, 1993 - Added a few more _SIZE #defines, clarified reserved
|
|
** values.
|
|
**
|
|
**
|
|
** GENERAL NOTES
|
|
** -------------
|
|
**
|
|
**
|
|
** Record Structure
|
|
** ----------------
|
|
**
|
|
** If not otherwise specified, all words are stored in Intel order: low-order
|
|
** word first, then high-order word, and inside of a word, low-order byte,
|
|
** then high-order byte. For example, a 32 bit quantity 0x12345678 would be
|
|
** written to the file as 0x78 0x56 0x34 0x12. The notable exception is the
|
|
** storage of point data in "standard compression" format. Sign bits are
|
|
** used to indicate item types, so the bytes are stored high-order to low-
|
|
** order (exactly opposite). See the sample code and reference section 23.0
|
|
** for more information on the compressed format. Uncompressed data is
|
|
** written in Intel order.
|
|
**
|
|
** All structures are packed for the purposes of writing to a stream.
|
|
**
|
|
** Signed integer values are two's-complement. Rectangles are stored
|
|
** x,y,w,h.
|
|
**
|
|
** These definitions are intended to insulate the sample ink compaction and
|
|
** storage code from any possible variation in item alignment or structure
|
|
** packing across architectures. The only possible area of portability
|
|
** concern lies in the use of unions in colors (see 11.0) and pen tips (see
|
|
** 14.0).
|
|
**
|
|
** Any use of units of mass to denote units of force ("grams of force"), or
|
|
** similar common misuses of physical units, are noted here with an apology
|
|
** to any purists, and should be interpreted in the common way by assuming
|
|
** one standard gravity.
|
|
**
|
|
** Record Sequence
|
|
** ---------------
|
|
**
|
|
** In this document, one piece of ink data is called an ink bundle.
|
|
** Typically this might correspond to the strokes that make up the ink from
|
|
** the time when the pen touches down until the user finishes writing
|
|
** (usually determined by a timeout or the pen leaving proximity). Thus an
|
|
** ink bundle usually contains many ink strokes, and the strokes do not have
|
|
** to describe a continuous line of ink.
|
|
**
|
|
** As stated in reference section 5.0, all data conforming to this
|
|
** specification appears as a stream of ink bundles each of which must begin
|
|
** with an INK_BUNDLE_RECORD and end with an INK_END_RECORD. There may be
|
|
** more than one INK_BUNDLE_RECORD/INK_END_RECORD pair in a given stream.
|
|
** A record stream might look something like this:
|
|
**
|
|
** INK_BUNDLE_RECORD required // for bundle number one
|
|
** INK_SCALE_RECORD optional // sets the scale for rendering
|
|
** INK_OFFSET_RECORD optional // sets the offset for rendering
|
|
** INK_COLOR_RECORD optional // sets the color for rendering
|
|
** INK_START_TIME_RECORD optional // sets the relative start time
|
|
** INK_PENTIP_RECORD optional // sets the pentip for rendering
|
|
** INK_GROUP_RECORD optional // tags the following PENDATA
|
|
** INK_PENDATA_RECORD recommended // actual points
|
|
** INK_GROUP_RECORD optional // tags the following PENDATA
|
|
** INK_PENDATA_RECORD recommended // actual points
|
|
** INK_PENDATA_RECORD recommended // more points in same group
|
|
** INK_SCALE_RESET_RECORD optional // resets to default scaling/offset
|
|
** INK_PENDATA_RECORD recommended // actual points
|
|
** INK_END_TIME_RECORD optional // relative time inking ended
|
|
** INK_END_RECORD required // end of bundle number one
|
|
**
|
|
** It is perfectly reasonable to write out only the following (though doing
|
|
** so will cause the ink to be rendered in a completely default manner --
|
|
** black hairline width at 1:1 scaling with offset 0):
|
|
**
|
|
** INK_BUNDLE_RECORD
|
|
** INK_PENDATA_RECORD
|
|
** INK_END_RECORD
|
|
**
|
|
**
|
|
** Specification Revisions
|
|
** -----------------------
|
|
**
|
|
** Future enhancements to this specification may modify certain record types.
|
|
** It is guaranteed that any record modified in a subsequent revision of the
|
|
** specification will be a strict superset of that record's definition in any
|
|
** previous revision of the specification. That is, modified record types
|
|
** will only be lengthened, not shortened. If a particular record type must
|
|
** be extended such that it would not be a superset of the original, a new
|
|
** record type would be added to cover that particular extension.
|
|
**
|
|
** This extension strategy has two important ramifications:
|
|
**
|
|
** 1) A reading application should *ALWAYS* use the size of a record as
|
|
** recorded in the record structure itself (i.e., the recordLength field
|
|
** of the INK_RECORD_HEADERx structure) rather than the sizeof() or any
|
|
** other size determined at compile time to determine how may bytes to
|
|
** read as the data structures are parsed. This is due to the fact that
|
|
** a record may grow in a future revision of the standard. The only
|
|
** exception to this rule is the INK_BUNDLE_RECORD which contains a
|
|
** version number that will be modified with each change to that record.
|
|
** If an INK_BUNDLE_RECORD is encountered and its version matches the
|
|
** version used at compile time, the size of the record should exactly
|
|
** match the #define of inkRecordBundleSize.
|
|
**
|
|
** 2) Any particular record may be read into a target data structure up to
|
|
** the size of the target data structure and the rest may be ignored.
|
|
** This is due to the 'strict superset' rule which means that any
|
|
** extension of any record type must leave the meaning, content, and size
|
|
** of any existing fields as is. So, for example, if an INK_SCALE_RECORD
|
|
** was modified by adding 2 bytes, the reading application can safely read
|
|
** the data into the INK_SCALE_RECORD known at compile time and throw
|
|
** away the extra two bytes: the header, x, and y will be in the same
|
|
** place and will have the same meaning.
|
|
**
|
|
**
|
|
** Files of Ink
|
|
** ------------
|
|
**
|
|
** It is a recommended practice on DOS and UNIX style file systems to use the
|
|
** extension ".JOT" for files consisting solely of ink recorded according to
|
|
** this specification. The specification is designed such that ink data can
|
|
** be embedded inside any file format and if such a file contains more than
|
|
** strictly ink data, it should not use the .JOT extension.
|
|
**
|
|
**------------------------------------------------------------------------*/
|
|
|
|
|
|
|
|
|
|
/*************************/
|
|
/* REFERENCE SECTION 2.0 */
|
|
/*************************/
|
|
|
|
/*-------------------------------------------------------------------------
|
|
** Definitions used in this header.
|
|
**
|
|
** These definitions must be defined appropriately to the target environment
|
|
** and compiler.
|
|
**
|
|
** For example, on some compilers for environments using segmented addressing
|
|
** and 64K segments sizes, the correct definition of FAR would be "_huge",
|
|
** rather than "_far", because the objects pointed to may be larger than 64K.
|
|
**
|
|
** In particular, check the definitions of FAR, U32, and S32 for
|
|
** compatibility with your compiler, environment, and memory model.
|
|
**
|
|
**------------------------------------------------------------------------*/
|
|
|
|
#ifndef FAR
|
|
#define FAR
|
|
#endif
|
|
|
|
/* useful constants */
|
|
|
|
#define flag0 (0x0001)
|
|
#define flag1 (0x0002)
|
|
#define flag2 (0x0004)
|
|
#define flag3 (0x0008)
|
|
#define flag4 (0x0010)
|
|
#define flag5 (0x0020)
|
|
#define flag6 (0x0040)
|
|
#define flag7 (0x0080)
|
|
#define flag8 (0x0100)
|
|
#define flag9 (0x0200)
|
|
#define flag10 (0x0400)
|
|
#define flag11 (0x0800)
|
|
#define flag12 (0x1000)
|
|
#define flag13 (0x2000)
|
|
#define flag14 (0x4000)
|
|
#define flag15 (0x8000)
|
|
|
|
#define flag16 (0x00010000L)
|
|
#define flag17 (0x00020000L)
|
|
#define flag18 (0x00040000L)
|
|
#define flag19 (0x00080000L)
|
|
#define flag20 (0x00100000L)
|
|
#define flag21 (0x00200000L)
|
|
#define flag22 (0x00400000L)
|
|
#define flag23 (0x00800000L)
|
|
#define flag24 (0x01000000L)
|
|
#define flag25 (0x02000000L)
|
|
#define flag26 (0x04000000L)
|
|
#define flag27 (0x08000000L)
|
|
#define flag28 (0x10000000L)
|
|
#define flag29 (0x20000000L)
|
|
#define flag30 (0x40000000L)
|
|
#define flag31 (0x80000000L)
|
|
|
|
#define TRUE 1
|
|
#define FALSE 0
|
|
|
|
/* void pointers */
|
|
typedef void FAR *P_UNKNOWN;
|
|
typedef P_UNKNOWN FAR *PP_UNKNOWN;
|
|
|
|
#define pNull ((P_UNKNOWN)0)
|
|
|
|
/* Unsigned integers */
|
|
typedef unsigned char U8, FAR *P_U8;
|
|
#define U8_SIZE 1
|
|
typedef unsigned short U16, FAR *P_U16;
|
|
#define U16_SIZE 2
|
|
typedef unsigned long U32, FAR *P_U32;
|
|
#define U32_SIZE 4
|
|
|
|
/* Signed integers */
|
|
typedef char S8, FAR *P_S8;
|
|
#define S8_SIZE 1
|
|
typedef short S16, FAR *P_S16;
|
|
#define S16_SIZE 2
|
|
typedef long S32, FAR *P_S32;
|
|
#define S32_SIZE 4
|
|
/*
|
|
typedef signed char S8, FAR *P_S8;
|
|
#define S8_SIZE 1
|
|
typedef signed short S16, FAR *P_S16;
|
|
#define S16_SIZE 2
|
|
typedef signed long S32, FAR *P_S32;
|
|
#define S32_SIZE 4
|
|
*/
|
|
|
|
/* geometry structures */
|
|
typedef struct tag_XY32 {
|
|
S32 x;
|
|
S32 y;
|
|
} XY32, FAR *P_XY32;
|
|
#define XY32_SIZE (S32_SIZE+S32_SIZE)
|
|
|
|
typedef struct tag_XY16 {
|
|
S16 x;
|
|
S16 y;
|
|
} XY16, FAR *P_XY16;
|
|
|
|
/*-------------------------------------------------------------------------
|
|
** Note:
|
|
** Angles from vertical can exceed +-90 degrees: in this case, the "back" end
|
|
** of the stylus is nearer the tablet surface than the "front" end.
|
|
**-------------------------------------------------------------------------*/
|
|
|
|
/*-------------------------------------------------------------------------
|
|
** Note:
|
|
** Standard compaction will normally store angles in nibbles, or single
|
|
** bytes, rather than in four-byte records.
|
|
**-------------------------------------------------------------------------*/
|
|
|
|
typedef struct tag_ANGLE16 {
|
|
S16 theta; /* "X" angle of the stylus, degrees from vertical, */
|
|
/* increasing in the positive "X" direction. */
|
|
S16 phi; /* "Y" angle of the stylus. */
|
|
} ANGLE16, FAR *P_ANGLE16;
|
|
#define ANGLE16_SIZE (S16_SIZE+S16_SIZE)
|
|
|
|
typedef struct tag_SIZE32 {
|
|
S32 w;
|
|
S32 h;
|
|
} SIZE32, FAR *P_SIZE32;
|
|
#define SIZE32_SIZE (S32_SIZE+S32_SIZE)
|
|
|
|
typedef struct tag_SIZE16 {
|
|
S16 w;
|
|
S16 h;
|
|
} SIZE16, FAR *P_SIZE16;
|
|
#define SIZE16_SIZE (S16_SIZE+S16_SIZE)
|
|
|
|
/*-------------------------------------------------------------------------
|
|
** Note:
|
|
** A rect where xmin==xmax and ymin==ymax has a size of zero:
|
|
** size.w and size.h are both zero.
|
|
**-------------------------------------------------------------------------*/
|
|
|
|
typedef struct tag_RECT32 {
|
|
XY32 origin;
|
|
SIZE32 size;
|
|
} RECT32, FAR *P_RECT32;
|
|
#define RECT32_SIZE (XY32_SIZE+SIZE32_SIZE)
|
|
|
|
typedef U32 FIXED_FRACTION; /* fixed point value, unity = 0x00010000 */
|
|
#define FIXED_FRACTION_SIZE U32_SIZE
|
|
|
|
#define INK_UNITY_SCALE ((U32) 0x00010000L)
|
|
|
|
|
|
|
|
|
|
/*************************/
|
|
/* REFERENCE SECTION 3.0 */
|
|
/*************************/
|
|
|
|
/*-------------------------------------------------------------------------
|
|
** A block of ink data is called an ink bundle. Each ink bundle consists of
|
|
** a series of n records. Each record has a common header that indicates the
|
|
** record type and the record length. An ink bundle always starts with an
|
|
** INK_BUNDLE_RECORD and always ends with an INK_END_RECORD.
|
|
**
|
|
** Any records of unknown type can be skipped by simply reading the length of
|
|
** the record.
|
|
**
|
|
** Note:
|
|
** Within an ink bundle, time increases. This implies a drawing order of
|
|
** back-to-front. Between adjacent sequential bundles, the implicit drawing
|
|
** is also back-to-front.
|
|
**
|
|
** A number of record types are defined. The most common is the
|
|
** inkRecordPenData which contains the actual pen data. Other records are
|
|
** mostly attributes of the pen data and are optional. They will, in
|
|
** general, only be present when a given attribute changes to something
|
|
** different than the default value for that attribute.
|
|
**
|
|
** In order to have the most compact format and also allow large records,
|
|
** several different record headers are defined, each with a different
|
|
** length.
|
|
**
|
|
** The top two bits of the record type indicate what kind of record length
|
|
** follows:
|
|
**
|
|
** The record length can be:
|
|
**
|
|
** - non-existent (the entire record consists of just the recordType)
|
|
** - An 8 bit length (one byte) for records up to 255 bytes
|
|
** - A 16 bit length (two bytes) for records up to 64k
|
|
** - A 32 bit length (four bytes) for really big records
|
|
**
|
|
**------------------------------------------------------------------------*/
|
|
|
|
#define inkRecordNoLength 0 /* no length, just recordType */
|
|
#define inkRecordLength8 flag14 /* 8 bit length */
|
|
#define inkRecordLength16 flag15 /* 16 bit length */
|
|
#define inkRecordLength32 (flag15 | flag14) /* 32 bit length */
|
|
|
|
/* useful defines for isolating or clearing the length type bits */
|
|
#define inkRecordLengthMask (flag15 | flag14) /* mask for length bits */
|
|
#define inkRecordLengthClearMask (~inkRecordLengthMask)
|
|
|
|
/* some useful macros for declaring the various types of record types */
|
|
#define MakeRec0(recType) (recType | inkRecordNoLength) /* no rec length */
|
|
#define MakeRec8(recType) (recType | inkRecordLength8) /* 8 bit length */
|
|
#define MakeRec16(recType) (recType | inkRecordLength16) /* 16 bit length */
|
|
#define MakeRec32(recType) (recType | inkRecordLength32) /* 32 bit length */
|
|
|
|
typedef U16 INK_RECORD_TYPE, FAR *P_INK_RECORD_TYPE;
|
|
#define INK_RECORD_TYPE_SIZE U16_SIZE
|
|
|
|
#define inkRecordHeaderLength(record_type) \
|
|
( (((record_type) & inkRecordLength32) == inkRecordNoLength) ?\
|
|
INK_RECORD_TYPE_SIZE \
|
|
: (((record_type) & inkRecordLength32) == inkRecordLength8) ?\
|
|
INK_RECORD_TYPE_SIZE+U8_SIZE \
|
|
: (((record_type) & inkRecordLength32) == inkRecordLength16) ?\
|
|
INK_RECORD_TYPE_SIZE+U16_SIZE \
|
|
: INK_RECORD_TYPE_SIZE+U32_SIZE \
|
|
)
|
|
|
|
/*-------------------------------------------------------------------------
|
|
** Note: most compilers will not generate code for the above macro but will
|
|
** determine the proper value at compile time.
|
|
**-------------------------------------------------------------------------*/
|
|
|
|
|
|
/*************************/
|
|
/* REFERENCE SECTION 4.0 */
|
|
/*************************/
|
|
|
|
/*-------------------------------------------------------------------------
|
|
** These are all the currently defined record types. The macro MakeRecX()
|
|
** encodes the right bits in with the record Id to define its recordLength.
|
|
**
|
|
** For simplicity, recType values may not be repeated for different
|
|
** INK_RECORD_TYPEs. Use of a record type defined as MakeRec32(63) thus
|
|
** forbids the use of a record type defined as MakeRec16(63), MakeRec8(63),
|
|
** or MakeRec0(63).
|
|
**
|
|
** Record type 63 is reserved explicitly for possible future extension beyond
|
|
** 63 record types.
|
|
**
|
|
**------------------------------------------------------------------------*/
|
|
|
|
#define inkRecordEnd MakeRec0( 0) /* end of bundle */
|
|
#define inkRecordBundle MakeRec8( 1)
|
|
#define inkRecordPenData MakeRec32( 2)
|
|
#define inkRecordScale MakeRec8( 3)
|
|
#define inkRecordScaleReset MakeRec0( 4)
|
|
#define inkRecordColor MakeRec8( 5)
|
|
#define inkRecordTip MakeRec8( 6)
|
|
#define inkRecordGroup MakeRec8( 7)
|
|
#define inkRecordOffset MakeRec8( 8)
|
|
#define inkRecordStartTime MakeRec8( 9)
|
|
#define inkRecordEndTime MakeRec8( 10)
|
|
#define inkRecordPointsPerSecond MakeRec8( 11)
|
|
#define inkRecordUnitsPerZ MakeRec8( 12)
|
|
#define inkRecordUnitsPerForce MakeRec8( 13)
|
|
|
|
/* Record types 14 .. 61 are reserved for future definition. */
|
|
|
|
#define inkRecordApp MakeRec32(62) /* application-specific records*/
|
|
#define inkRecordExt MakeRec32(63) /* reserved for extension */
|
|
|
|
/*-------------------------------------------------------------------------
|
|
** Every record starts with a header that contains the recordType and the
|
|
** recordLength. The recordType indicates the type of data here. The
|
|
** recordLength indicates the total length of all the data for the record
|
|
** (including the size of the header).
|
|
**-------------------------------------------------------------------------*/
|
|
|
|
/* no recordLength */
|
|
typedef struct tag_INK_RECORD_HEADER0 {
|
|
INK_RECORD_TYPE recordType;
|
|
} INK_RECORD_HEADER0, FAR *P_INK_RECORD_HEADER0;
|
|
|
|
/* 8 bit recordLength */
|
|
typedef struct tag_INK_RECORD_HEADER8 {
|
|
INK_RECORD_TYPE recordType;
|
|
U8 recordLength;
|
|
} INK_RECORD_HEADER8, FAR *P_INK_RECORD_HEADER8;
|
|
|
|
/* 16 bit recordLength */
|
|
typedef struct tag_INK_RECORD_HEADER16 {
|
|
INK_RECORD_TYPE recordType;
|
|
U16 recordLength;
|
|
} INK_RECORD_HEADER16, FAR *P_INK_RECORD_HEADER16;
|
|
|
|
/* 32 bit recordLength */
|
|
typedef struct tag_INK_RECORD_HEADER32 {
|
|
INK_RECORD_TYPE recordType;
|
|
U32 recordLength;
|
|
} INK_RECORD_HEADER32, FAR *P_INK_RECORD_HEADER32;
|
|
|
|
|
|
|
|
|
|
/*************************/
|
|
/* REFERENCE SECTION 5.0 */
|
|
/*************************/
|
|
|
|
/*-------------------------------------------------------------------------
|
|
** A bundle of ink consists of an INK_BUNDLE_RECORD, a series of records,
|
|
** terminated with an INK_END_RECORD.
|
|
**
|
|
** An INK_BUNDLE_RECORD, along with a matching INK_END_RECORD, are the
|
|
** mandatory records in the format. The ink data must start with an
|
|
** INK_BUNDLE_RECORD.
|
|
**
|
|
** It is suggested that anyone reading this format do a number of validity
|
|
** checks on the first record in any ink data. The first record should meet
|
|
** the following minimum requirements:
|
|
**
|
|
** 1) header.recordType == INK_RECORD_BUNDLE
|
|
** 2) header.recordLength >= inkRecordBundleSize (See general notes in
|
|
** reference section 1.0 for important information about record sizes.)
|
|
** 3) compactionType is an expected and supported value
|
|
** 4) penUnitsPerX and penUnitsPerY seem reasonable and expected:
|
|
** greater than, say, 1000 units per meter (25.4/inch), less than, say,
|
|
** 400,000 (~10,000 units per inch)
|
|
**
|
|
**------------------------------------------------------------------------*/
|
|
|
|
typedef struct tag_INK_END_RECORD {
|
|
INK_RECORD_HEADER0 header; /* value is inkRecordEnd */
|
|
} INK_END_RECORD, FAR *P_INK_END_RECORD;
|
|
#define inkRecordEndSize (inkRecordHeaderLength(inkRecordEnd))
|
|
|
|
|
|
|
|
|
|
/*************************/
|
|
/* REFERENCE SECTION 6.0 */
|
|
/*************************/
|
|
|
|
/*-------------------------------------------------------------------------
|
|
** The terms compression and compaction are used somewhat interchangeably
|
|
** in this specification but they actually have slightly different meanings
|
|
** and are both supported to a certain extent by Jot.
|
|
**
|
|
** Compression refers to a technique of encoding data such that the resuling
|
|
** data, while smaller, is still whole. That is, compression under Jot is
|
|
** loss-less. Compaction refers to a process where certain pieces of less
|
|
** important data are actually omitted from the stream and are possibly
|
|
** reconstructed by the reader of the data.
|
|
**
|
|
** Using Jot, a writing application may choose to compress only, compact only
|
|
** or use some combination. The standard compression mechanism defined here
|
|
** and implemented in the sample code supports both notions.
|
|
**
|
|
**------------------------------------------------------------------------*/
|
|
|
|
typedef U8 INK_COMPACTION_TYPE, FAR *P_INK_COMPACTION_TYPE;
|
|
#define INK_COMPACTION_TYPE_SIZE U8_SIZE
|
|
#define inkNoCompression (0)
|
|
#define inkStdCompression (1)
|
|
|
|
/*-------------------------------------------------------------------------
|
|
** Other compression schemes may be adopted in future revisions of this
|
|
** specification.
|
|
**-------------------------------------------------------------------------*/
|
|
|
|
|
|
|
|
|
|
/*************************/
|
|
/* REFERENCE SECTION 7.0 */
|
|
/*************************/
|
|
|
|
/*-------------------------------------------------------------------------
|
|
** The INK_BUNDLE_FLAGS contain some flags that apply to an entire bundle.
|
|
** If you wanted to store several pieces of ink that had different
|
|
** INK_BUNDLE_FLAGS, you would do it by storing several different bundles.
|
|
**
|
|
** Advisory flags:
|
|
**
|
|
** inkPointsRemoved
|
|
** Indicates whether all original points are still present or whether
|
|
** some points were removed to save space. For applications that are
|
|
** only interested in the visual aspects of ink, many points can be
|
|
** removed that do not affect the appearance (i.e. duplicate points,
|
|
** collinear points, points which deviate less than some screen
|
|
** resolution, etc..). Some other types of applications must know that
|
|
** points are present at some consistent sampling rate (i.e. some forms
|
|
** of handwriting translation). This flag indicates whether all
|
|
** original points are still there.
|
|
**
|
|
** Note:
|
|
** The purpose of "inkPointsRemoved" is to indicate that the timing
|
|
** information cannot be accurately derived by counting points:
|
|
** replacing individual points with an "elided point" item does not
|
|
** constitute removing points. ("Elided" means omitted or skipped).
|
|
**
|
|
** inkProxDataRemoved
|
|
** Indicates that the original points between strokes (proximity) were
|
|
** removed to save space. An out-of-prox point should be stored between
|
|
** strokes to delimit them. Some applications depend on knowing the
|
|
** time between strokes or at the ends of strokes for certain
|
|
** functions.
|
|
**
|
|
** Note:
|
|
** "Proximity" is defined as the stylus being close enough to the tablet
|
|
** for the tablet to report the stylus position, although perhaps at
|
|
** lower accuracy and perhaps at a lower number of points per second. A
|
|
** recommended practice is to include "out of proximity" points in the
|
|
** recorded ink data when they are used as part of determining the
|
|
** amount of time a stylus was out of contact with the tablet, or for
|
|
** triggering the completion of an action such as a "gesture".
|
|
**
|
|
** inkStrokeLimitsPresent
|
|
** Indicates that INK_BUTTONS items are also present, and that they
|
|
** indicate what the storing app decided the stroke start/end points
|
|
** were. (Note: the reading application may otherwise use a different
|
|
** algorithm for using tip force values to delimit strokes.)
|
|
**
|
|
** Note:
|
|
** If inkStrokeLimitsPresent is set, then inkButtonDataPresent must also
|
|
** be set.
|
|
**
|
|
** Data flags:
|
|
**
|
|
** inkAngleDataPresent indicates angle data is present.
|
|
** inkForceDataPresent indicates force data is present.
|
|
** inkProxDataPresent indicates points are present when pen is lifted
|
|
** up (i.e. the force drops below some threshold).
|
|
** inkRotationDataPresent indicates pen rotation data is present.
|
|
** inkHeightDataPresent indicates pen height data is present.
|
|
** inkButtonDataPresent indicates "button state" information is present.
|
|
** inkPreMultiplyScale indicates that scaling should be applied before
|
|
** the offset value is added ("pre-multiply")
|
|
** rather than after ("post-multiply")
|
|
**
|
|
** Note:
|
|
** A previous draft version included a provision for compacting data to an
|
|
** approximation based on Bezier curves. Initial results did not show
|
|
** promise in terms of efficiency and performance.
|
|
**
|
|
** "inkBezierRepresentation" would have indicated that the X/Y ordinates
|
|
** reflected a Bezier approximation to the original tablet data. This would
|
|
** have meant that the ordinate data represented aggregates of anchor points
|
|
** and control points for each piece wise approximation, and therefore could
|
|
** not be used directly to render the data. The definition of these anchor
|
|
** and control points, and the example code for the approximation and
|
|
** regeneration of the "true" coordinates could not be worked out at this
|
|
** time.
|
|
**
|
|
** Some standard values for pen units per meter follow:
|
|
**
|
|
** 1000 points per inch digitizer == 39370 pen units per meter
|
|
** 500 points per inch digitizer == 19685 pen units per meter
|
|
** 200 points per inch digitizer == 7874 pen units per meter
|
|
** 254 points per inch (1/10 mm) == 10000 pen units per meter
|
|
**
|
|
** 1000 pen units per meter is a reasonable minimum; 400,000 is a reasonable
|
|
** maximum value.
|
|
**
|
|
** The specific format for each of these types of data is described in the
|
|
** INK_PENDATA_RECORD documentation (reference section 8.0).
|
|
**
|
|
** Note:
|
|
** The order in which these flags are defined has nothing to do with the
|
|
** order in which the data appears in the INK_POINT structure when reading
|
|
** or writing point data. For more information, see reference section 21.0.
|
|
**
|
|
**------------------------------------------------------------------------*/
|
|
|
|
typedef U16 INK_BUNDLE_FLAGS, FAR *P_INK_BUNDLE_FLAGS;
|
|
#define INK_BUNDLE_FLAGS_SIZE U16_SIZE
|
|
#define inkPointsRemoved (flag0)
|
|
#define inkProxDataRemoved (flag1)
|
|
#define inkAngleDataPresent (flag2)
|
|
#define inkForceDataPresent (flag3)
|
|
#define inkRotationDataPresent (flag4)
|
|
#define inkHeightDataPresent (flag5)
|
|
#define inkButtonDataPresent (flag6)
|
|
#define inkStrokeLimitsPresent (flag7)
|
|
#define inkPreMultiplyScale (flag8)
|
|
|
|
/*-------------------------------------------------------------------------
|
|
** Reserved: flag9, flag10, flag11, flag12, flag13, flag14, flag15.
|
|
** More flags beyond flag15 can be added in a new record type
|
|
** in a later revision to this specification.
|
|
**-------------------------------------------------------------------------*/
|
|
|
|
|
|
typedef struct tag_INK_BUNDLE_RECORD {
|
|
INK_RECORD_HEADER8 header; /* value is inkRecordBundle */
|
|
U8 version; /* Value for release 1.0 is 1 */
|
|
INK_COMPACTION_TYPE compactionType;
|
|
INK_BUNDLE_FLAGS flags; /* flags for the whole bundle */
|
|
U32 penUnitsPerX; /* pen units per meter (x dir) */
|
|
U32 penUnitsPerY; /* pen units per meter (y dir) */
|
|
} INK_BUNDLE_RECORD, FAR *P_INK_BUNDLE_RECORD;
|
|
|
|
#define inkPointDefaultVersion (1)
|
|
#define inkPointDefaultCompactionType (inkStdCompression)
|
|
#define inkPointDefaultBundleFlags (0)
|
|
#define inkPointDefaultPenUnitsPerX (1000)
|
|
#define inkPointDefaultPenUnitsPerY (1000)
|
|
|
|
#define inkRecordBundleSize \
|
|
(inkRecordHeaderLength(inkRecordBundle) + U8_SIZE + \
|
|
INK_COMPACTION_TYPE_SIZE + INK_BUNDLE_FLAGS_SIZE + \
|
|
U32_SIZE + U32_SIZE)
|
|
|
|
|
|
|
|
|
|
/*************************/
|
|
/* REFERENCE SECTION 8.0 */
|
|
/*************************/
|
|
|
|
/*-------------------------------------------------------------------------
|
|
** A penData record contains the actual pen data for one or more pen strokes.
|
|
** The bounds applies to all the strokes contained within this record.
|
|
** Multiple strokes are typically grouped into one record to increase the
|
|
** efficiency of the compression algorithm, though strokes may be stored
|
|
** individually, if desired.
|
|
**
|
|
** The bounds is the pure mathematical bounds of the raw pen points and does
|
|
** not take into account any rendering information such as the pen tip or the
|
|
** line width. All points in the INK_PENDATA have been normalized relative
|
|
** to the lower bounds in the INK_PENDATA header.
|
|
**
|
|
** Some applications will prefer to know the bounds of individual strokes.
|
|
** This can be accomplished in two ways.
|
|
**
|
|
** 1) The bounds for a given stroke can be computed when reading the file
|
|
** by decompressing an INK_PENDATA_RECORD into its strokes and then
|
|
** traversing the points in each stroke to build the bounds for each
|
|
** stroke.
|
|
**
|
|
** 2) An application can decide to store only one stroke per
|
|
** INK_PENDATA_RECORD (and thus the bounds of the PENDATA_RECORD is
|
|
** already the bounds of one stroke). The sacrifice here is in
|
|
** compression efficiency and the need to still support reading files
|
|
** written by other applications that might group multiple strokes
|
|
** into a single INK_PENDATA_RECORD.
|
|
**
|
|
** Note:
|
|
** In practice, our experience is that unpacking the data in order to compute
|
|
** the bounds for each stroke to check for strokes that intrude into a given
|
|
** region is not an excessive burden. The checks that would have been done
|
|
** on the bounds of each stroke can be done on the builds for each penData
|
|
** group, and not all strokes must be checked individually.
|
|
**
|
|
** The format of the pen data is determined by the settings for
|
|
** compactionType and flags in the INK_BUNDLE_RECORD structure, and
|
|
** is described later in this file. Two formats are currently defined:
|
|
** an uncompacted format and a delta-encoded compacted format, both with
|
|
** optional components present or absent depending on the state of the flags
|
|
** in the INK_BUNDLE_RECORD.
|
|
**
|
|
**------------------------------------------------------------------------*/
|
|
|
|
typedef struct tag_INK_PENDATA_RECORD {
|
|
INK_RECORD_HEADER32 header; /* value is inkRecordPenData */
|
|
RECT32 bounds;
|
|
U8 inkData[1]; /* ink data goes here: definitions */
|
|
/* follow later in this file. */
|
|
} INK_PENDATA_RECORD, FAR *P_INK_PENDATA_RECORD;
|
|
#define inkRecordPenDataSize(data_length) \
|
|
(inkRecordHeaderLength(inkRecordPenData) + RECT32_SIZE + (data_length))
|
|
|
|
|
|
|
|
|
|
/*************************/
|
|
/* REFERENCE SECTION 9.0 */
|
|
/*************************/
|
|
|
|
/*-------------------------------------------------------------------------
|
|
** Ink scale is recorded in two fixed point values. A unity scale (scale
|
|
** of one) is represented as 0x00010000, a scale of 0.5 as 0x00008000.
|
|
**
|
|
** Note:
|
|
** All ink is located relative to the lower-left (0,0) corner of a logical
|
|
** page or window. Scale and offset operations are cumulative, much in the
|
|
** same way as in PostScript. One begins with a normalized graphics state
|
|
** and sequentially applies the scale and offset operations to that matrix.
|
|
** The INK_SCALE_RESET record returns the graphics state to its default state
|
|
** (i.e., the transformation matrix is set to an identity matrix and the
|
|
** offset is reset to the default of 0). By default, scaling is applied
|
|
** after adding in any offset specified in an INK_OFFSET_RECORD. If the ink
|
|
** bundle has the inkPreMultiplyScale bit set, for all ink in that bundle
|
|
** scaling is applied before adding in any offset.
|
|
**
|
|
** As used in this format, ink scale and offset values are set by the storing
|
|
** application, to be applied by the rendering application. If the storing
|
|
** application collected the ink at scales of (2.0,2.0), the storing
|
|
** application should insert an INK_SCALE_RECORD with a scale of (0.5,0.5)
|
|
** for the rendering application to multiply all ink X and Y coordinates by.
|
|
**
|
|
** It is the responsibility of the storing application to deal with any
|
|
** effects from round-off or truncation error due to the limits of precision
|
|
** in the FIXED_FRACTION values used in INK_SCALE_RECORDs.
|
|
**
|
|
** An ink scale record indicates a scale change that stays in effect until
|
|
** another ink scale record is encountered. Ink scale values compound: if
|
|
** the current scale is (2.0,2.0) and an INK_SCALE_RECORD is encountered with
|
|
** scale of (2.0,3.0), the scale to be applied to ink then becomes(4.0,6.0).
|
|
** In absence of any ink scale record, the default ink scale is unity. In
|
|
** general, a typical usage pattern for an application that supports drawing
|
|
** ink while zoomed at scale is to record a number of strokes at a given
|
|
** scale, reset the scale with an INK_SCALE_RESET_RECORD (which resets both
|
|
** the scale and the offset to the default values), then switch to another
|
|
** scale, then record a number more strokes, and so on.
|
|
**
|
|
** Note:
|
|
** The extension scaling and offset to the Z ordinate value is not defined in
|
|
** this version of the specification. The extension to Z scaling and offset
|
|
** in a "standard" record type (i.e. not an application-specific record) may
|
|
** be addressed in the future.
|
|
**
|
|
**------------------------------------------------------------------------*/
|
|
|
|
typedef struct tag_INK_SCALE {
|
|
FIXED_FRACTION x; /* scale in the x direction */
|
|
FIXED_FRACTION y; /* scale in the y direction */
|
|
} INK_SCALE, FAR *P_INK_SCALE;
|
|
#define INK_SCALE_SIZE (FIXED_FRACTION_SIZE+FIXED_FRACTION_SIZE)
|
|
|
|
#define inkPointDefaultScale (INK_UNITY_SCALE) /* Unity. */
|
|
|
|
typedef struct tag_INK_SCALE_RECORD {
|
|
INK_RECORD_HEADER8 header; /* value is inkRecordScale */
|
|
INK_SCALE scale;
|
|
} INK_SCALE_RECORD, FAR *P_INK_SCALE_RECORD;
|
|
#define inkRecordScaleSize \
|
|
(inkRecordHeaderLength(inkRecordScale) + \
|
|
FIXED_FRACTION_SIZE + FIXED_FRACTION_SIZE)
|
|
|
|
|
|
|
|
|
|
/**************************/
|
|
/* REFERENCE SECTION 10.0 */
|
|
/**************************/
|
|
|
|
/*-------------------------------------------------------------------------
|
|
** The offset position is used to relocate ink data, after scaling. For
|
|
** example, in a forms application, ink in a sketch field is drawn relative
|
|
** to a given sketch field in the form. The location of this original field
|
|
** is important to know so we know how the ink in this bundle relates to its
|
|
** original field. If we wanted to move this ink to another field (i.e.
|
|
** cut/paste or move), we would need to know the location of the original
|
|
** field so we could render the ink in the new field in a manner consistent
|
|
** with how it was drawn relative to its original field (i.e. a similar
|
|
** baseline for a hand-written signature).
|
|
**
|
|
** This record is optional. If it exists, it will then apply to all
|
|
** following pen data in the file. If it is not present it is assumed that
|
|
** no information of this type is relevant. For example, while field ink
|
|
** would have an offset position, markup ink over an entire form would not
|
|
** have a offset position (or would have an offset position of (0,0) and a
|
|
** scale of (1,1)) because it is relative to the entire form coordinate
|
|
** system, not relative to some piece in the form.
|
|
**
|
|
** Note:
|
|
** This approach allows a reader to "blindly" apply the scale and offset
|
|
** values specified to ink data, and puts the burden for computing
|
|
** compounding of multiple zoom levels, etc., on the writing application.
|
|
**
|
|
**------------------------------------------------------------------------*/
|
|
|
|
typedef struct tag_INK_OFFSET_RECORD {
|
|
INK_RECORD_HEADER8 header; /* value is inkRecordOffset */
|
|
XY32 positionOffset; /* values are in pen units */
|
|
} INK_OFFSET_RECORD, FAR *P_INK_OFFSET_RECORD;
|
|
|
|
#define inkRecordOffsetSize \
|
|
(inkRecordHeaderLength(inkRecordOffset) + XY32_SIZE)
|
|
|
|
#define inkPointDefaultOffset ((S32) 0) /* No offset. */
|
|
|
|
|
|
typedef struct tag_INK_SCALE_RESET_RECORD {
|
|
INK_RECORD_HEADER0 header; /* value is inkRecordScaleReset */
|
|
} INK_SCALE_RESET_RECORD, FAR *P_INK_SCALE_RESET_RECORD;
|
|
|
|
#define inkRecordScaleResetSize (inkRecordHeaderLength(inkRecordScaleReset))
|
|
|
|
|
|
|
|
|
|
/**************************/
|
|
/* REFERENCE SECTION 11.0 */
|
|
/**************************/
|
|
|
|
/*-------------------------------------------------------------------------
|
|
** Ink color is represented as an rgb value, plus opacity.
|
|
**
|
|
** The default color is black (r,g,b,o) = (0,0,0,255). A color change
|
|
** present in the file remains in effect until another color change.
|
|
** Typically, the color will stay the same for many ink strokes and thus
|
|
** a color record will only be used occasionally when the color changes.
|
|
**
|
|
** "Opacity" is rather vaguely understood, especially in color environments.
|
|
** In this context, opacity means the degree to which the display underneath
|
|
** the ink shows through. An opacity value of 255 means that nothing under
|
|
** the ink shows through; 0 means that everything shows through (the ink
|
|
** is transparent). It is up to the reading application to define the
|
|
** implementation of opacity on the reading platform.
|
|
**
|
|
** The color/opacity value of (255,255,255,0), or "transparent white" is
|
|
** defined as an "erase" color. In inking applications that support a true
|
|
** "erase" function, such as the ability to erase annotation ink on an
|
|
** "original" document (perhaps a FAX image) the "erase" color restores the
|
|
** background image where painted. The "background image" is defined by the
|
|
** rendering application.
|
|
**
|
|
** Applications which do not support a true "erase" function may interpret
|
|
** this as some other drawing function, such as drawing the "background"
|
|
** color.
|
|
**
|
|
**------------------------------------------------------------------------*/
|
|
|
|
typedef union {
|
|
U32 all;
|
|
struct {
|
|
U8 red,
|
|
green,
|
|
blue,
|
|
opacity; /* opaqueness: see defines below */
|
|
} rgb;
|
|
} INK_COLOR, FAR *P_INK_COLOR;
|
|
#define INK_COLOR_SIZE (U32_SIZE)
|
|
|
|
typedef struct tag_INK_COLOR_RECORD {
|
|
INK_RECORD_HEADER8 header; /* value is inkRecordColor */
|
|
INK_COLOR color;
|
|
} INK_COLOR_RECORD, FAR *P_INK_COLOR_RECORD;
|
|
#define inkRecordColorSize \
|
|
(inkRecordHeaderLength(inkRecordColor) + U32_SIZE)
|
|
|
|
/*-------------------------------------------------------------------------
|
|
** Standardized opacity values:
|
|
** A recommended practice is that an opacity value of 128 (midway between
|
|
** 0 and 255) be used for "highlighter" colors. A recommended practice is
|
|
** that grey values as defined below be used for "standard grey"
|
|
** highlighters.
|
|
**-------------------------------------------------------------------------*/
|
|
|
|
#define inkOpacityTransparent 0x00
|
|
#define inkOpacityHighlight 0x80
|
|
#define inkOpacityOpaque 0xFF
|
|
|
|
/* Standard solid colors: */
|
|
|
|
#define inkColorErase {0xFF,0xFF,0xFF,0x00}
|
|
#define inkColorWhite {0xFF,0xFF,0xFF,0xFF}
|
|
#define inkColorLtGrey {0x80,0x80,0x80,0xFF}
|
|
#define inkColorDkGrey {0x40,0x40,0x40,0xFF}
|
|
#define inkColorBlack {0x00,0x00,0x00,0xFF}
|
|
|
|
/* Standard highlighter (transparent) colors: */
|
|
|
|
#define inkColorLtGreyHighlight {0x80,0x80,0x80,0x80}
|
|
#define inkColorDkGreyHighlight {0x40,0x40,0x40,0x80}
|
|
|
|
#define inkDefaultColor ((INK_COLOR) inkColorBlack)
|
|
|
|
|
|
|
|
|
|
/**************************/
|
|
/* REFERENCE SECTION 12.0 */
|
|
/**************************/
|
|
|
|
/*-------------------------------------------------------------------------
|
|
** Time is measured in milliseconds.
|
|
**
|
|
** Note:
|
|
** Because of the difficulty synchronizing clocks on different machines
|
|
** at the time granularity of digitizing tablets, and because the "editing"
|
|
** of ink at a later time makes the definition of the absolute time for each
|
|
** ink point ambiguous, the base for the time is arbitrary. All times in
|
|
** strokes are just relative to each other with no absolute time
|
|
** relationship.
|
|
**
|
|
** These records, when encountered in the file, apply to the next stroke data
|
|
** in the file (so this record comes before the penData that it applies to).
|
|
** End time records are not required. The interpretation of an end time
|
|
** which is in conflict with the end time inferred from the assumed data rate
|
|
** of points and the number of points (including elided points) is not
|
|
** defined.
|
|
**
|
|
** Start time is the time for the first point in the following penData record
|
|
** and end time is the time of the last point in the following penData
|
|
** record, because if you are recording tip force, the exact definition of
|
|
** pen up and pen down may be fuzzy and/or application dependent.
|
|
**
|
|
**------------------------------------------------------------------------*/
|
|
|
|
typedef U32 INK_TIME, FAR *P_INK_TIME; /* milliseconds */
|
|
#define INK_TIME_SIZE U32_SIZE
|
|
|
|
#define inkDefaultTime ((INK_TIME) 0)
|
|
|
|
typedef struct tag_INK_START_TIME_RECORD {
|
|
INK_RECORD_HEADER8 header; /* value is inkRecordStartTime */
|
|
INK_TIME startTime;
|
|
} INK_START_TIME_RECORD, FAR *P_INK_START_TIME_RECORD;
|
|
#define inkRecordStartTimeSize \
|
|
(inkRecordHeaderLength(inkRecordStartTime) + INK_TIME_SIZE)
|
|
|
|
typedef struct tag_INK_END_TIME_RECORD {
|
|
INK_RECORD_HEADER8 header; /* value is inkRecordEndTime */
|
|
INK_TIME endTime;
|
|
} INK_END_TIME_RECORD, FAR *P_INK_END_TIME_RECORD;
|
|
#define inkRecordEndTimeSize \
|
|
(inkRecordHeaderLength(inkRecordEndTime) + INK_TIME_SIZE)
|
|
|
|
|
|
|
|
|
|
/**************************/
|
|
/* REFERENCE SECTION 13.0 */
|
|
/**************************/
|
|
|
|
/*-------------------------------------------------------------------------
|
|
** INK_PENDATA_RECORDs can be grouped. If they are grouped, each
|
|
** INK_PENDATA_RECORD can be assigned a group number. All
|
|
** INK_PENDATA_RECORDs with the same group number belong to the same group.
|
|
**
|
|
** The exact interpretation of grouping is up the applications involved.
|
|
** Writing applications may group ink data, but not all reading applications
|
|
** that read the data may interpret grouping in the same way.
|
|
**
|
|
** For example, grouping could be used in the traditional fashion as in
|
|
** drawing programs so the user moves or copies an entire group of
|
|
** INK_PENDATA_RECORDs together. A group could also be used to signify a
|
|
** series of INK_PENDATA_RECORDs entered by the user all within some criteria
|
|
** (i.e. all during one proximity session or all within some time frame).
|
|
**
|
|
** Group numbers are simply signed 16 bit values and can be anything. They
|
|
** do not need to be contiguous (i.e. they do not need to be 0,1,2). They
|
|
** can be 12,49,-12345 if that is useful.
|
|
**
|
|
** This record can also be used as a simple marker for starting a new group
|
|
** when the groupId is not really used: Group numbers of 0,0,0,0 ... are
|
|
** thus permitted.
|
|
**
|
|
** INK_GROUPs are nestable. Group 0 is reserved as the end-of-group marker
|
|
** for disjoint groups. If no end-of-group marker is encountered before the
|
|
** end of the file or the end of all ink data (as indicated by an
|
|
** INK_END_RECORD), all current (and possibly nested) groups are terminated
|
|
** as if end-of-groups markers for them had been encountered.
|
|
**
|
|
**------------------------------------------------------------------------*/
|
|
|
|
typedef S32 INK_GROUP, FAR *P_INK_GROUP;
|
|
#define INK_GROUP_SIZE S32_SIZE
|
|
|
|
typedef struct tag_INK_GROUP_RECORD {
|
|
INK_RECORD_HEADER8 header; /* value is inkRecordGroup */
|
|
INK_GROUP groupId; /* application-specific interpretation */
|
|
} INK_GROUP_RECORD, FAR *P_INK_GROUP_RECORD;
|
|
|
|
#define inkDefaultGroup ((INK_GROUP) 0)
|
|
|
|
#define inkRecordGroupSize \
|
|
(inkRecordHeaderLength(inkRecordGroup) + INK_GROUP_SIZE)
|
|
|
|
|
|
|
|
|
|
/**************************/
|
|
/* REFERENCE SECTION 14.0 */
|
|
/**************************/
|
|
|
|
/*-------------------------------------------------------------------------
|
|
** Some applications may support the idea of rendering ink as if it were
|
|
** drawn by a certain shaped pen tip. The most common pen tips would be
|
|
** round or rectangular. The exact details of how to render a given pen
|
|
** tip will be application specific, but this record states what pen tip
|
|
** parameters were used by the storing app.
|
|
**
|
|
** Pen tips determine, in part, how ink is rendered. For pen tip types
|
|
** defined in future versions of this format which require additional
|
|
** parameters (such as the X and Y rectangle for a simulated nib pen, or
|
|
** brush dimensions for a simulated brush), additional data is included
|
|
** at the end of the structure.
|
|
**
|
|
** The writing application should be aware that the reading application will
|
|
** only do "the best possible" job of rendering and that fully compliant
|
|
** reading applications may not be able to render certain nib types and/or
|
|
** colors. Both reading and writing applications should pay particular
|
|
** attention to the following notes regarding defaults and ink drawn at a
|
|
** width of zero.
|
|
**
|
|
** A pen tip which is drawing ink in zero width renders at the minimum
|
|
** visible width the reading application will support.
|
|
**
|
|
** A recommended practice is that ink which should not render (should this
|
|
** be called for) be drawn with a color value of (0,0,0, 0), i.e., black,
|
|
** completely transparent.
|
|
**
|
|
** Pen tip size should scale when an INK_SCALE_RECORD is encountered. The
|
|
** writing application should write a new INK_PENTIP_RECORD after an
|
|
** INK_SCALE_RECORD if the writing application does not want the pen tip
|
|
** size to scale along with the ink. If the pen tip scales to zero width,
|
|
** it should be rendered by the reading application according to the comment
|
|
** above.
|
|
**
|
|
** The default pen tip if no pentip record exists is INK_PENTIP_ROUND, with a
|
|
** width of one twip. The dimensions of a round nib specify diameter, not
|
|
** radius: the X/Y coordinate is the center of this diameter. Similarly, for
|
|
** for rectangular nibs, the X/Y coordinate is the center of the rectangle.
|
|
**
|
|
** Note:
|
|
** This specification does not specify information for an algorithmic
|
|
** variation in nib width, ink color, or other "brush" effects as a function
|
|
** of tip force, speed or any other factor. An example would be for an
|
|
** application to draw wider ink as the user presses down harder with the
|
|
** stylus. Applications wishing to implement such features may do so using
|
|
** application-specific record types for this revision of the specification.
|
|
**
|
|
**------------------------------------------------------------------------*/
|
|
|
|
typedef S16 INK_PENTIP, FAR *P_INK_PENTIP;
|
|
#define INK_PENTIP_SIZE S16_SIZE
|
|
#define INK_PENTIP_ROUND (0) /* Diameter in twips */
|
|
#define INK_PENTIP_RECTANGLE (1) /* Dimensions in twips */
|
|
#define INK_PENTIP_SLANT_RECTANGLE (2)
|
|
#define INK_PENTIP_ROUND_FLAT_END (3)
|
|
/* ... more to be filled in here if needed */
|
|
|
|
#define inkDefaultPentip INK_PENTIP_ROUND
|
|
#define inkDefaultPentipData ((U16) 1)
|
|
|
|
typedef struct tag_INK_PENTIP_SLANT {
|
|
SIZE16 rectangle_size; /* INK_PENTIP_SLANTRECTANGLE */
|
|
U16 angle; /* Whole degrees from vertical, counter-clockwise */
|
|
} INK_PENTIP_SLANT, FAR *P_INK_PENTIP_SLANT;
|
|
|
|
typedef union {
|
|
U16 round_width; /* INK_PENTIP_ROUND */
|
|
SIZE16 rectangle_size; /* INK_PENTIP_RECTANGLE */
|
|
INK_PENTIP_SLANT slant; /* INK_PENTIP_SLANT_RECTANGLE */
|
|
U16 round_flat_width; /* INK_PENTIP_ROUND_FLAT_END */
|
|
} INK_PENTIP_DATA, FAR *P_INK_PENTIP_DATA;
|
|
|
|
/* Size of the union is determined by INK_PENTIP_SLANT */
|
|
#define INK_PENTIP_DATA_SIZE (SIZE16_SIZE+U16_SIZE)
|
|
|
|
typedef struct tag_INK_PENTIP_RECORD {
|
|
INK_RECORD_HEADER8 header; /* value is inkRecordTip */
|
|
INK_PENTIP tip;
|
|
INK_PENTIP_DATA tip_data;
|
|
} INK_PENTIP_RECORD, FAR *P_INK_PENTIP_RECORD;
|
|
#define inkRecordTipSize \
|
|
(inkRecordHeaderLength(inkRecordTip) + INK_PENTIP_SIZE + \
|
|
SIZE16_SIZE + U16_SIZE)
|
|
|
|
|
|
|
|
|
|
/**************************/
|
|
/* REFERENCE SECTION 15.0 */
|
|
/**************************/
|
|
|
|
/*-------------------------------------------------------------------------
|
|
** For some applications, it will be important to know the sampling rate of
|
|
** the pen digitizer.
|
|
**
|
|
** This record would likely be present once in a bundle and would typically
|
|
** be after the INK_BUNDLE_RECORD, but before the first pen data.
|
|
**
|
|
** Note:
|
|
** Writing applications are not required to report the "true" sampling rate
|
|
** of the digitizer, nor are rendering applications required to play back the
|
|
** ink at the specified rate. It is likely that most types of rendering
|
|
** applications will render ink as rapidly as possible to construct a display
|
|
** in minimum time, and that some types of animation applications will
|
|
** intentionally set an arbitrary sampling rate to vary the display rate.
|
|
**
|
|
** Note:
|
|
** For hardware which supports a highly variable sampling rate, the writing
|
|
** application can simulate a very high sampling rate (say, 1000 points/
|
|
** second), and use skip records for "elided" points to achieve an exact time
|
|
** value (at 1-millisecond resolution) for each point.
|
|
**
|
|
** A default value for sampling rate has been arbitrarily defined below.
|
|
**
|
|
**------------------------------------------------------------------------*/
|
|
|
|
typedef struct tag_INK_POINTS_PER_SECOND_RECORD {
|
|
INK_RECORD_HEADER8 header; /* value is inkRecordPointsPerSecond */
|
|
U16 pointsPerSecond;
|
|
} INK_POINTS_PER_SECOND_RECORD, FAR *P_INK_POINTS_PER_SECOND_RECORD;
|
|
|
|
#define inkPointDefaultPointsPerSecond (100)
|
|
|
|
#define inkRecordPointsPerSecondSize \
|
|
(inkRecordHeaderLength(inkRecordPointsPerSecond) + U16_SIZE)
|
|
|
|
|
|
|
|
|
|
/**************************/
|
|
/* REFERENCE SECTION 16.0 */
|
|
/**************************/
|
|
|
|
/*-------------------------------------------------------------------------
|
|
** Units for Z height of stylus above the tablet.
|
|
**
|
|
** This record would only be present once in a bundle and would typically be
|
|
** after the INK_BUNDLE_RECORD, but before the first pen data.
|
|
**
|
|
**------------------------------------------------------------------------*/
|
|
|
|
typedef struct tag_INK_UNITS_PER_Z_RECORD {
|
|
INK_RECORD_HEADER8 header; /* value is inkRecordUnitsPerZ */
|
|
U32 unitsPerZ; /* pen units per meter (Z height) */
|
|
} INK_UNITS_PER_Z_RECORD, FAR *P_INK_UNITS_PER_Z_RECORD;
|
|
|
|
#define inkPointDefaultUnitsPerZ (10000) /* 0.1 mm units */
|
|
|
|
#define inkRecordUnitsPerZSize \
|
|
(inkRecordHeaderLength(inkRecordUnitsPerZ) + U32_SIZE)
|
|
|
|
|
|
|
|
|
|
/**************************/
|
|
/* REFERENCE SECTION 17.0 */
|
|
/**************************/
|
|
|
|
/*-------------------------------------------------------------------------
|
|
** Units for stylus tip force.
|
|
**
|
|
** This record would only be present once in a bundle and would typically be
|
|
** after the INK_BUNDLE_RECORD, but before the first pen data.
|
|
**
|
|
** Note:
|
|
** This specification assumes some level of accuracy and linearity for tip
|
|
** force data, if such data is present. However, since tip force sensors in
|
|
** current digitizer tablet and stylus designs may well vary in accuracy and
|
|
** linearity from one unit to the next even for hardware of the same design
|
|
** and model, and since algorithms for using tip force to determine stroke
|
|
** start and end are likely to differ, a recommended practice for writing
|
|
** applications that use the tip force value to determine the "touch" points
|
|
** in a stroke is to mark those points using the touch bit in the INK_BUTTONS
|
|
** structure.
|
|
**
|
|
** It is also recommended that vendors supporting tip force sensing in their
|
|
** hardware linearize their transducers to the greatest extent possible.
|
|
**
|
|
** Because of the likelihood that tip force transducers may not be accurately
|
|
** linearized, negative tip force values, while perhaps somewhat absurd
|
|
** are possible and are permitted in this specification.
|
|
**
|
|
**------------------------------------------------------------------------*/
|
|
|
|
typedef struct tag_INK_UNITS_PER_FORCE_RECORD {
|
|
INK_RECORD_HEADER8 header; /* value is inkRecordUnitsPerForce */
|
|
U32 unitsPerForce; /* tip-force units per k-gram of force*/
|
|
} INK_UNITS_PER_FORCE_RECORD, FAR *P_INK_UNITS_PER_FORCE_RECORD;
|
|
|
|
#define inkPointDefaultUnitsPerForce (1000) /* grams of force */
|
|
|
|
#define inkRecordUnitsPerForceSize \
|
|
(inkRecordHeaderLength(inkRecordUnitsPerForce) + U32_SIZE)
|
|
|
|
|
|
|
|
|
|
/**************************/
|
|
/* REFERENCE SECTION 18.0 */
|
|
/**************************/
|
|
|
|
/*-------------------------------------------------------------------------
|
|
** The INK_APP_RECORD record is a universal record to be used by individual
|
|
** applications to put data into the file that is not supported by an
|
|
** additional publicly defined record type. The basic idea is that an
|
|
** application puts its own unique application signature into the appData
|
|
** bytes in the INK_APP_RECORD. This identifies the data as originating with
|
|
** a particular application. Then, an application defines a set of
|
|
** subRecordTypes that they wish to use. Then, using these subRecordTypes
|
|
** they can put a wide variety of information into the file. By examining
|
|
** the appData signature and comparing it to theirs, an application can
|
|
** decide whether it knows how to interpret the various subRecordtypes.
|
|
**
|
|
**------------------------------------------------------------------------*/
|
|
|
|
typedef struct tag_INK_APP_RECORD {
|
|
INK_RECORD_HEADER32 header; /* value is inkRecordApp */
|
|
U8 appSignature[8];/* reserved for possible unique */
|
|
/* application signature */
|
|
U16 subRecordType;
|
|
/* data here appropriate to the subRecordType and appData signature */
|
|
} INK_APP_RECORD, FAR *P_INK_APP_RECORD;
|
|
#define inkRecordAppSize(data_length) \
|
|
(inkRecordHeaderLength(inkRecordApp) + 8 + U16_SIZE + (data_length))
|
|
|
|
|
|
|
|
|
|
/**************************/
|
|
/* REFERENCE SECTION 19.0 */
|
|
/**************************/
|
|
|
|
/*-------------------------------------------------------------------------
|
|
** Definition of the inkData components of an INK_PENDATA_RECORD:
|
|
**
|
|
** Uncompacted point format:
|
|
** -------------------------
|
|
**
|
|
** This structure immediately follows the rest of the INK_PENDATA_RECORD.
|
|
** The structure has several optional components, present or not present as
|
|
** indicated by the INK_BUNDLE_FLAGS in the INK_BUNDLE_RECORD. The format is
|
|
** a sequence of "point values", each containing all the scalar data for each
|
|
** sampled tablet point.
|
|
**
|
|
** In the uncompacted format, there is a single structure that contains all
|
|
** of the state information for each point from the tablet. Components not
|
|
** present (as indicated by the INK_BUNDLE_FLAGS) are just that: not present,
|
|
** do not exist, do not occupy space.
|
|
**
|
|
** Compacted point format:
|
|
** -----------------------
|
|
**
|
|
** In the compacted format, "State values", such as the stylus state of
|
|
** touch/no-touch/out-of-prox or the on/off state of the barrel switches, are
|
|
** stored in a compacted "INK_BUTTONS" item (represented using reserved
|
|
** encodings in the INK_POINT coordinate values) interjected when their state
|
|
** changes. The initial state is assumed to be "not touching", "out of
|
|
** proximity", all barrel switches "off". It is possible to have both tip
|
|
** force data, and explicit starts and ends of strokes: the starts and ends
|
|
** of the strokes are then points that were considered to be such by the
|
|
** original application storing the data. The INK_BUTTONS record reflects
|
|
** the state of the next X/Y point following.
|
|
**
|
|
**------------------------------------------------------------------------*/
|
|
|
|
|
|
|
|
|
|
/**************************/
|
|
/* REFERENCE SECTION 20.0 */
|
|
/**************************/
|
|
|
|
/*-------------------------------------------------------------------------
|
|
** "INK_BUTTONS" items may most often be used only to indicate stylus touch
|
|
** and out-of-prox state, and perhaps a single barrel button. The format is
|
|
** optimized for this case. The format extends to a total of 28 stylus/puck
|
|
** buttons.
|
|
**
|
|
**------------------------------------------------------------------------*/
|
|
|
|
/*-------------------------------------------------------------------------
|
|
** The lowest-order bit (flag0) is "0" when the stylus is out of
|
|
** proximity, "1" when it is in proximity.
|
|
** Second lowest-order bit (flag1) is "1" to indicate the next inkPoints are
|
|
** when the stylus is touching (the start of a stroke: tip-switch "on"),
|
|
** "0" to indicate that the stylus is not touching (end of a stroke).
|
|
** Third bit (flag2) indicates state of first (or only) barrel switch,
|
|
** etc.
|
|
** 31'st bit (flag30) is normally "0", "1" is indicates there are more
|
|
** than 29 barrel/puck buttons with state, and the rest are in the next
|
|
** four-byte word.
|
|
**-------------------------------------------------------------------------*/
|
|
|
|
typedef U32 INK_BUTTONS, FAR * P_INK_BUTTONS;
|
|
|
|
/*-------------------------------------------------------------------------
|
|
** These definitions hold the maximum and minimum values that
|
|
** can be used with the S15 and S31 representations described in
|
|
** this document:
|
|
**-------------------------------------------------------------------------*/
|
|
|
|
#define MAX_S31 ((S32) 0x3FFFFFFF)
|
|
#define MIN_S31 ((S32) 0xC0000000)
|
|
|
|
#define MAX_S15 ((S16) 0x3FFF)
|
|
#define MIN_S15 ((S16) 0xC000)
|
|
|
|
#define MAX_S7 ((S16) 0x003F)
|
|
#define MIN_S7 ((S16) 0xFFC0)
|
|
|
|
#define MAX_S3 ((S16) 0x0003)
|
|
#define MIN_S3 ((S16) 0xFFFC)
|
|
|
|
/* SignExtend4/8/16/32: Sign-extend an S3, S7, S15, S31 to an S32: */
|
|
|
|
#define SignExtend4(value) ((S32) \
|
|
(((value)&0x00000004l)== 0 ? ((value)&0x00000007l) \
|
|
: (((value)&0x00000007l) | 0xFFFFFFF8l)))
|
|
|
|
#define SignExtend8(value) ((S32) \
|
|
(((value)&0x00000040l)== 0 ? ((value)&0x0000007Fl) \
|
|
: (((value)&0x0000007Fl) | 0xFFFFFF80l)))
|
|
|
|
#define SignExtend16(value) ((S32) \
|
|
(((value)&0x00004000l)== 0 ? ((value)&0x00007FFFl) \
|
|
: (((value)&0x00007FFFl) | 0xFFFF8000l)))
|
|
|
|
#define SignExtend32(value) ((S32) \
|
|
(((value)&0x40000000l)== 0 ? ((value)&0x7FFFFFFFl) \
|
|
: (((value)&0x7FFFFFFFl) | 0x80000000l)))
|
|
|
|
|
|
|
|
/**************************/
|
|
/* REFERENCE SECTION 21.0 */
|
|
/**************************/
|
|
|
|
/*-------------------------------------------------------------------------
|
|
** INK_POINT data. The INK_POINT structure varies in size depending on
|
|
** flags set in the bundle header. The XY32 position is always present, but
|
|
** the force, rho, height, angle, and buttons members are only present when
|
|
** indicated by the corresponding flag in the bundle header. When optional
|
|
** data is present, it is present in the order defined by this structure;
|
|
** that is, position, force, height, rho, angle, and finally buttons.
|
|
**
|
|
** The INK_POINT structure has the following elements:
|
|
**
|
|
** position - required and always present
|
|
** Positions are measured with (0,0) at the lower-left, X increasing to
|
|
** the right, Y increasing upwards. Values are actually S31, not S32.
|
|
** The high bit in X and Y must be zero.
|
|
** force - optional, present if inkForceDataPresent is asserted
|
|
** Units are in pen force units, zero is no contact.
|
|
** height - optional, present if inkHeightDataPresent is asserted
|
|
** Units are in pen unitsPerZ as specified by inkPointDefaultUnitsPerZ or
|
|
** by an INK_UNITS_PER_Z_RECORD, whichever is appropriate. Units increase
|
|
** as the stylus is taken away from the tablet. Zero means "just in
|
|
** contact". Negative values could possibly result from spring action if
|
|
** the stylus is pressed hard, or if the tablet is not perfectly accurate.
|
|
** rho - optional, present if inkRotationDataPresent is asserted
|
|
** Angles are measured in degrees from some nominal orientation of
|
|
** "stylus button on top" (somewhat arbitrary). Angles increase with
|
|
** clockwise rotation as seen from the rear end of the stylus.
|
|
** angle - optional, present if inkAngleDataPresent is asserted
|
|
** Angles are measured in pen angle units from the vertical. Theta
|
|
** increases in the positive-X direction, phi in the positive-Y.
|
|
** buttons - optional, present if inkButtonDataPresent is asserted
|
|
**
|
|
** When the INK_BUNDLE_RECORD member compactionType is inkStdCompression,
|
|
** all data in this structure is compressed according to the methods
|
|
** described in reference section 23.0. For more details on how to interpret
|
|
** the compressed data stream, see the sample code. The bundle flags which
|
|
** indicate whether a particular piece of data is present are used regardless
|
|
** of whether the data is compressed or not. Note that when data is written
|
|
** in compressed format, it is NOT written in Intel order but rather most
|
|
** significant byte first. In compressed form, some of the eight bit delta
|
|
** values are reserved for button data and elided (skipped) point counts.
|
|
** This has two important ramifications. 1) When expecting a point,
|
|
** compacted button data or elided point data may be encountered instead, and
|
|
** 2) when the inkButtonDataPresent flag is asserted in the bundle header,
|
|
** button data will appear in the place of a point and not in addition to a
|
|
** point. If inkButtonDataPresent is not asserted, the reader need not check
|
|
** the point data for the special case of button data; however, the point
|
|
** data must still be checked to see if it is a count of elided points rather
|
|
** than an actual point.
|
|
**
|
|
**------------------------------------------------------------------------*/
|
|
|
|
typedef struct tag_INK_POINT {
|
|
XY32 position; /* required x/y point data */
|
|
S16 force; /* optional force data */
|
|
S16 height; /* optional z height data */
|
|
S16 rho; /* optional rotational data */
|
|
ANGLE16 angle; /* optional theta and phi data */
|
|
INK_BUTTONS buttons; /* optional proximity, contact, button data */
|
|
} INK_POINT, FAR *P_INK_POINT;
|
|
|
|
|
|
|
|
|
|
/**************************/
|
|
/* REFERENCE SECTION 22.0 */
|
|
/**************************/
|
|
|
|
|
|
/*-------------------------------------------------------------------------
|
|
** The following default values are assumed before the start of any
|
|
** INK_BUNDLE:
|
|
**
|
|
**------------------------------------------------------------------------*/
|
|
|
|
|
|
#define inkPointDefaultXYPosition ((S32) 0)
|
|
#define inkPointDefaultForce ((S16) 0)
|
|
#define inkPointDefaultHeight ((S16) 0)
|
|
#define inkPointDefaultRho ((S16) 0)
|
|
#define inkPointDefaultAngle ((S16) 0)
|
|
#define inkPointDefaultButtons ((U32) 0)
|
|
|
|
|
|
|
|
|
|
/**************************/
|
|
/* REFERENCE SECTION 23.0 */
|
|
/**************************/
|
|
|
|
/*-------------------------------------------------------------------------
|
|
** Compacted point format:
|
|
** ---------------------
|
|
**
|
|
** A recommended practice is always to use the compacted point format, not
|
|
** the uncompacted point format. Sample code for reading and writing the
|
|
** compacted format is included in an appendix.
|
|
**
|
|
** This structure also immediately follows the rest of the
|
|
** INK_PENDATA_RECORD.
|
|
**
|
|
** The uncompacted values above are stored in sequential bytes in a more
|
|
** compact, delta-oriented format. Deltas are all signed values, a value to
|
|
** add to the previous value. The first point in an INK_PENDATA_RECORD is
|
|
** always relative to the defined default values for each component of the
|
|
** point.
|
|
**
|
|
** The storing application, as an alternative to eliminating points, can
|
|
** specify a "skip" record for elided points. The skipRecord indicates that
|
|
** a number of points were skipped, and the reading application is free to
|
|
** insert values for the elided points (interpolating where appropriate).
|
|
** The intent is to allow for accurate time information to be maintained
|
|
** between time stamps for synchronization with recorded voice, press-hold
|
|
** gesture recognition, etc.
|
|
**
|
|
** Compacted data is written most significant byte first so that reading
|
|
** applications can read the first byte and determine (from the top two bits)
|
|
** how large the encoded delta is.
|
|
**
|
|
** Note:
|
|
** "Reserved encodings" are those encodings that, if real points, would fit
|
|
** into the next smaller delta size. 16 bit deltas and 8 bit deltas have
|
|
** reserved encodings. The reserved encodings for 16 bit deltas are all 16
|
|
** bit delta pairs where both X and Y are within the inclusive range MIN_S7
|
|
** and MAX_S7. Similarly, the reserved encoding for 8 bit deltas are all 8
|
|
** bit delta pairs where both X and Y are within the inclusive range MIN_S3
|
|
** and MAX_S3. In revision 1.0 of Jot, three of the reserved encodings for 8
|
|
** bit deltas are used for special cases: skip counts (reference section
|
|
** 27.0) and button changes (reference section 26.0).
|
|
**
|
|
** x/y position:
|
|
** ------------
|
|
**
|
|
** 32-bit absolute X/Y:
|
|
**
|
|
** Two 32 bit long words: Data is actually two S31s:
|
|
**
|
|
** |0|0| (30 low-order bits of X) |
|
|
** ... Sign bit is taken from first bit of next word.
|
|
** ----------------------------------------------------------------
|
|
** |X| (sign bit of X plus 31 bits of Y) |
|
|
** ----------------------------------------------------------------
|
|
**
|
|
** 16-bit short delta X/Y:
|
|
**
|
|
** Short words: two 16 bit words: Deltas are actually two S15s:
|
|
** Values that would fit into an 8-bit byte delta are reserved.
|
|
**
|
|
** |0|1| (14 low-order bits of delta-X) |
|
|
** ... Sign bit is taken from first bit of next word.
|
|
** --------------------------------------------------
|
|
** |X| (sign bit of X plus 15 bits of delta Y |
|
|
** --------------------------------------------------
|
|
**
|
|
** 8-bit byte delta X/Y:
|
|
**
|
|
** Bytes: two bytes: Deltas are actually two S7s:
|
|
** Values that would fit into a 4-bit nibble delta are reserved.
|
|
**
|
|
** |1|0| (6 low-order bits of delta-X) |
|
|
** ... Sign bit is taken from first bit of next word.
|
|
** ------------------------------------------
|
|
** |X| (7 bits of delta-Y) |
|
|
** ------------------------------------------
|
|
**
|
|
** 4-bit nibble delta X/Y:
|
|
**
|
|
** Nibbles: one byte: Deltas are actually S3:
|
|
**
|
|
** |1|1| (S3 delta-X) | (S3 delta-Y) |
|
|
** -----------------------------------
|
|
**
|
|
**------------------------------------------------------------------------*/
|
|
|
|
|
|
|
|
|
|
/**************************/
|
|
/* REFERENCE SECTION 24.0 */
|
|
/**************************/
|
|
|
|
/*-------------------------------------------------------------------------
|
|
** Tip force:
|
|
** ----------
|
|
**
|
|
** 16-bit absolute force:
|
|
**
|
|
** Short word: one word: Value is actually S15:
|
|
** Values that would fit into an 8-bit byte delta are reserved.
|
|
**
|
|
** |0| (15 bits of force) |
|
|
** ---------------------------------------------
|
|
**
|
|
** 8-bit byte delta force:
|
|
**
|
|
** Byte: one byte: Deltas are actually S7:
|
|
**
|
|
** |1| (S7 delta-force) |
|
|
** --------------------------
|
|
**
|
|
**
|
|
** Height:
|
|
** ------
|
|
**
|
|
** (Same encoding as tip force)
|
|
**
|
|
** Rho:
|
|
** ---
|
|
**
|
|
** (Same encoding as tip force)
|
|
**
|
|
**
|
|
** Stylus theta-phi:
|
|
** ----------------
|
|
**
|
|
** 16-bit absolute theta-phi:
|
|
**
|
|
** Short words: two words: Data is actually S15:
|
|
**
|
|
** |0|0| (14 low-order bits of theta) |
|
|
** -------------------------------------------
|
|
** ... Sign bit is taken from first bit of next word.
|
|
** |X| (15 bits of phi) |
|
|
** -------------------------------------------
|
|
**
|
|
**------------------------------------------------------------------------*/
|
|
|
|
|
|
|
|
|
|
/**************************/
|
|
/* REFERENCE SECTION 25.0 */
|
|
/**************************/
|
|
|
|
/*-------------------------------------------------------------------------
|
|
** 8-bit byte delta theta-phi
|
|
**
|
|
** Bytes: two bytes: Deltas are actually S7:
|
|
** Values that would fit into a 4-bit nibble delta are reserved.
|
|
**
|
|
** |0|1| (6 low-order bits of delta-theta)|
|
|
** --------------------------------------------
|
|
** ... Sign bit is taken from first bit of next word.
|
|
** |X| (7 bits of delta-phi) |
|
|
** --------------------------------------------
|
|
**
|
|
** 4-bit nibble delta theta-phi
|
|
**
|
|
** Nibbles: one byte: Deltas are actually S3:
|
|
**
|
|
** |1|0|(S3 delta-theta)|(S3 delta-phi)|
|
|
** -------------------------------------
|
|
**
|
|
** Note:
|
|
** Leading bit values of |1|1| are reserved
|
|
**
|
|
**------------------------------------------------------------------------*/
|
|
|
|
|
|
|
|
|
|
/**************************/
|
|
/* REFERENCE SECTION 26.0 */
|
|
/**************************/
|
|
|
|
/*-------------------------------------------------------------------------
|
|
** Since the X/Y data is always present, we use some of the reserved delta
|
|
** encodings to encode button states and elided (skipped) points. We use the
|
|
** 8-bit delta encodings that are unused: the values that can fit into the
|
|
** smaller 4-bit delta encodings.
|
|
**
|
|
** Button/tip records:
|
|
** ------------------
|
|
**
|
|
** It is assumed that the state of barrel buttons and the touching sensor on
|
|
** the stylus change infrequently. A compacted button/tip record is only
|
|
** included when the state changes in one of the switches. The button state
|
|
** value applies to the X/Y point immediately following the button state
|
|
** record.
|
|
**
|
|
**
|
|
** (Taken from 8-bit byte delta X/Y: two bytes total)
|
|
**
|
|
** |1|0| 0|0|0|0|0|0/1| 0|X|.|.|.|.|X|X|
|
|
** ---------------------------------------
|
|
** (delta-X) (delta-Y)
|
|
**
|
|
** An eight-bit delta with delta-X == 0 or 1, and delta-Y in the range
|
|
** (-4..3) indicates a button state encoding.
|
|
**
|
|
** It is likely to be the case that many hardware platforms have only one
|
|
** barrel button.
|
|
**
|
|
** The three delta-Y bits indicate the "touch", "out-of-prox", and "first
|
|
** barrel button" state as follows:
|
|
**
|
|
** low-order delta-Y bit: 1 --> in proximity, 0 --> out of prox
|
|
** next delta-Y bit: 1 --> touching tablet, 0 --> not touching
|
|
** high-order (sign) delta-Y bit: 1 --> first button closed, 0 --> open
|
|
**
|
|
**
|
|
** The lowest order bit of the delta-X bits is used to indicate that
|
|
** additional bytes follow: "1" indicates that the next byte is used for the
|
|
** next 7 barrel buttons with state. The high order bit of each sequential
|
|
** byte in the series is "1" if an additional byte must be fetched, "0"
|
|
** otherwise. In these additional bytes, the additional buttons are
|
|
** associated in order starting with the low-order bit.
|
|
**
|
|
**------------------------------------------------------------------------*/
|
|
|
|
|
|
|
|
/**************************/
|
|
/* REFERENCE SECTION 27.0 */
|
|
/**************************/
|
|
|
|
/*-------------------------------------------------------------------------
|
|
** Skipped-point records:
|
|
** ---------------------
|
|
**
|
|
** (Taken from 8-bit byte delta X/Y: two bytes total)
|
|
**
|
|
**
|
|
** |1|0| 0|0|0|0|1|0| 0|X|.|.|.|.|X|X|
|
|
** -------------------------------------
|
|
** (delta-X) (delta-Y)
|
|
**
|
|
** An eight-bit delta with delta-X == 2, and delta-Y in the range
|
|
** (-4..3) indicates a count of elided points. The delta-Y values in the
|
|
** range (-4..-1) are used to represent skip counts of (4..7). If the
|
|
** delta-Y value is zero "0", the next two bytes are fetched to get a U16
|
|
** skip count value.
|
|
**
|
|
** The elided points are points removed between the point immediately prior
|
|
** to the skipped-point record and the point immediately afterward. This
|
|
** implies that at least one point must follow every skip record (though
|
|
** the point may not appear next in the stream if there are intervening
|
|
** button state transitions). Reading applications that are interested in
|
|
** recovering elided points will typically interpolate. Skip counts of zero
|
|
** are meaningless and not permitted.
|
|
**
|
|
** Reserved:
|
|
** --------
|
|
**
|
|
** The remaining encodings from the 8-bit byte delta X/Y are reserved:
|
|
**
|
|
** delta-X of -4, -3, -2, -1, 3 AND ((delta-Y >= -4) & ((delta-Y <= 3))
|
|
**
|
|
**------------------------------------------------------------------------*/
|
|
|
|
#endif /* end of INKSTORE_INCLUDED */
|