FORMATS/FLT.txt

   1 /* Copyright (C) 2003, 2004
   2      National Institute of Advanced Industrial Science and Technology (AIST)
   3      Registration Number H15PRO112
   4    See the end for copying conditions.  */
   5
   6 /***en
   7
   8 @page mdbFLT Font Layout Table
   9
  10 @section flt-description DESCRIPTION
  11
  12 For simple scripts, the rendering engine converts character codes into glyph
  13 codes one by one by consulting the encoding of each selected font.
  14 But, to render text that requires complicated layout (e.g. Thai and
  15 Indic scripts), one to one conversion is not sufficient.  A sequence
  16 of characters may have to be drawn as a single ligature.  Some
  17 glyphs may have to be drawn at 2-dimensionally shifted positions.
  18
  19 To handle those complicated scripts, the m17n library uses Font Layout
  20 Tables (FLTs for short).  The FLT driver interprets an FLT and
  21 converts a character sequence into a glyph sequence that is ready to
  22 be passed to the rendering engine.
  23
  24 An FLT can contain information to extract a grapheme cluster from a
  25 character sequence and to reorder the characters in the cluster, in
  26 addition to information found in OpenType Layout Tables (CMAP, GSUB,
  27 and GPOS).
  28
  29 An FLT is a cascade of one or more conversion stages.  In each stage, a
  30 sequence is converted into another sequence to be read in the
  31 next stage.  The length of sequences may differ from stage to
  32 stage.  Each element in a sequence has the following integer attributes.
  33
  34 <ul>
  35 <li> code
  36
  37 In the first conversion stage, this is the character code in the
  38 original character sequence.  In the last stage, it is the glyph code
  39 passed to the rendering engine.  In other cases, it is an intermediate
  40 glyph code.
  41
  42 <li> category
  43
  44 This is the category code defined in the @c CATEGORY-TABLE
  45 of the current stage.
  46
  47 <li> combining-spec
  48
  49 If nonzero, it specifies how to combine this (intermediate) glyph
  50 with the previous one.
  51
  52 <li> left-padding-flag
  53
  54 If nonzero, it instructs the rendering function to insert a padding
  55 space before this (intermediate) glyph so that the glyph does not
  56 overlap with the previous one.
  57
  58 <li> right-padding-flag
  59
  60 If nonzero, it instructs the rendering function to insert a padding
  61 space after this (intermediate) glyph so that the glyph does not
  62 overlap with the next one.
  63
  64 </ul>
  65
  66 When the layout engine draws text, it at first determines a font and
  67 an FLT for each character in the text.  For each subsequence of
  68 characters that use use the same font and FLT, the layout engine
  69 generates an intermediate glyph sequence from the character
  70 subsequence.  Each element in the intermediate glyph sequence
  71 has the corresponding character code as the code attribute and zeroes
  72 for other attributes.  This sequence is processed in the
  73 first stage of FLT as the current @e run (substring).
  74
  75 Each stage works as follows.
  76
  77 At first, if the stage has a @c CATEGORY-TABLE, the category of each glyph
  78 in the current run is updated.  If there is a glyph that has no category,
  79 the current run ends before that glyph.
  80
  81 Then, the default values of code-offset, combining-spec, and left-padding-flag
  82 of this stage are initialized to zero.
  83
  84 Next, the initial conversion rule of the stage is applied to the
  85 current run.
  86
  87 Lastly, the current run is replaced with the newly produced
  88 (intermediate) glyph sequence.
  89
  90 @section flt-syntax SYNTAX and SEMANTICS
  91
  92 The m17n library loads an FLT from the m17n database using the tag
  93 \<font, layouter, FLT-NAME\>.  The date format of an FLT is as follows:
  94
  95 @verbatim
  96 FONT-LAYOUT-TABLE ::= STAGE0 STAGE *
  97
  98 STAGE0 ::= CATEGORY-TABLE GENERATOR
  99
 100 STAGE ::= CATEGORY-TABLE ? GENERATOR
 101
 102 CATEGORY-TABLE ::= '(' 'category' CATEGORY-SPEC + ')'
 103
 104 CATEGORY-SPEC ::= '(' CODE CATEGORY ')'
 105                   | '(' CODE CODE CATEGORY ')'
 106
 107 CODE ::= INTEGER
 108
 109 CATEGORY ::= INTEGER
 110 @endverbatim
 111
 112 In the definition of @c CATEGORY-SPEC, @c CODE is a glyph code, and @c
 113 CATEGORY is ASCII code of an upper or lower letter, i.e. one of 'A',
 114 ... 'Z', 'a', .. 'z'.
 115
 116 The first form of @c CATEGORY-SPEC assigns @c CATEGORY to a glyph
 117 whose code @c CODE.  The second form assigns @c CATEGORY to glyphs
 118 whose code falls between the two @c CODEs.
 119
 120 @verbatim
 121 GENERATOR ::= '(' 'generator' RULE MACRO-DEF * ')'
 122
 123 RULE ::= REGEXP-BLOCK | MATCH-BLOCK | SUBST-BLOCK | COND-BLOCK
 124          | DIRECT-CODE | COMBINING-SPEC | OTF-SPEC
 125          | PREDEFINED-RULE | MACRO-NAME
 126
 127 MACOR-DEF ::= '(' MACRO-NAME RULE + ')'
 128 @endverbatim
 129
 130 Each @c RULE specifies glyphs to be consumed and glyphs to be produced.  When
 131 some glyphs are consumed, they are taken away from the current run.  A
 132 rule may fail in some condition.  If not described explicitly to
 133 fail, it should be regarded that the rule succeeds.
 134
 135 @verbatim
 136 DIRECT-CODE ::= INTEGER
 137 @endverbatim
 138
 139 This rule consumes no glyph and produces a glyph which has the
 140 following attributes:
 141
 142 <ul>
 143 <li> code : @c INTEGER plus the default code-offset
 144 <li> combining-spec : default value
 145 <li> left-padding-flag : default value
 146 <li> right-padding-flag : zero
 147 </ul>
 148
 149 After having produced the glyph, the default code-offset,
 150 combining-spec, and left-padding-flag are all reset to zero.
 151
 152 @verbatim
 153 PREDEFINED-RULE ::= '=' | '*' | '<' | '>' | '|' | '[' | ']'
 154 @endverbatim
 155
 156 They perform actions as follows.
 157
 158 <ul>
 159 <li> @c =
 160
 161 This rule consumes the first glyph in the current run and produces the
 162 same glyph.  It fails if the current run is empty.
 163
 164 <li> @c *
 165
 166 This rule repeatedly executes the previous rule.
 167 If the previous rule fails, this rule does nothing and fails.
 168
 169 <li> @c @<
 170
 171 This rule specifies the start of a grapheme cluster.
 172
 173 <li> @c @>
 174
 175 This rule specifies the end of a grapheme cluster.
 176
 177 <li> @c @[
 178
 179 This rule sets the default left-padding-flag to 1.
 180 No glyph is consumed.  No glyph is produced.
 181
 182 <li> @c @]
 183
 184 This rule changes the right-padding-flag of the lastly generated
 185 glyph to 1.
 186 No glyph is consumed.  No glyph is produced.
 187
 188 <li> @c |
 189
 190 This rule consumes no glyph and produces a special glyph whose
 191 category is ' ' and other attributes are zero.
 192 This is the only rule that produces that special glyph.
 193
 194 </ul>
 195
 196 @verbatim
 197 REGEXP-BLOCK ::= '(' REGEXP RULE * ')'
 198
 199 REGEXP ::= MTEXT
 200 @endverbatim
 201
 202 @c MTEXT is a regular expression that should match the sequence of
 203 categories of the current run.  If a match is found, this rule
 204 executes @c RULEs temporarily limiting the current run to the matched
 205 part.  The matched part is consumed by this rule.
 206
 207 Parenthesized subexpressions, if any, are recorded to be used in @c
 208 MATCH-BLOCK that may appear in one of @c RULEs.
 209
 210 If no match is found, this rule fails.
 211
 212 @verbatim
 213 MATCH-BLOCK ::= '(' MATCH-INDEX RULE * ')'
 214
 215 MATCH-INDEX ::= INTEGER
 216 @endverbatim
 217
 218 MATCH-INDEX is an integer specifying a parenthesized subexpression
 219 recoded by the previous @c REGEXP-BLOCK.  If such a subexpression was
 220 found by the previous regular expression matching, this rule executes @c
 221 RULEs temporarily limiting the current run to the matched part
 222 of the subexpression.  The matched part is consumed by this rule.
 223
 224 If no match was found, this rule fails.
 225
 226 If this is the first rule of the stage, @c MATCH-INDEX must be 0, and
 227 it matches the whole current run.
 228
 229 @verbatim
 230 SUBST-BLOCK ::= '(' SOURCE-PATTERN RULE * ')'
 231
 232 SOURCE-PATTERN ::= '(' CODE + ')'
 233                    | (' 'range' CODE CODE ')'
 234 @endverbatim
 235
 236 If the sequence of codes of the current run matches @c SOURCE-PATTERN,
 237 this rule executes @c RULEs temporarily limiting the current run to
 238 the matched part.  The matched part is consumed.
 239
 240 The first form of @c SOURCE-PATTERN specifies a sequence of glyph codes to be
 241 matched.  In this case, this rule resets the default code-offset to
 242 zero.
 243
 244 The second form specifies a range of codes that should match the first
 245 glyph code of the code sequence.  In this case, this rule sets the
 246 default code-offset to the first glyph code minus the first @c CODE in @c
 247 SOURCE-RANGE.
 248
 249 If no match is found, this rule fails.
 250
 251 @verbatim
 252 COND-BLOCK ::= '(' 'cond' RULE + ')'
 253 @endverbatim
 254
 255 This rule sequentially executes @c RULEs until one succeeds.  If no
 256 rule succeeds, this rule fails.  Otherwise, it succeeds.
 257
 258 @verbatim
 259 OTF-SPEC ::= SYMBOL
 260 @endverbatim
 261
 262 @c OTF-SPEC is a symbol whose name specifies an instruction to the OTF
 263 driver.  The name has the following syntax.
 264
 265 @verbatim
 266   OTF-SPEC-NAME ::= 'otf:' SCRIPT LANGSYS ? GSUB-FEATURES ? GPOS-FEATURES ?
 267
 268   SCRIPT ::= SYMBOL
 269
 270   LANGSYS ::= '/' SYMBOL
 271
 272   GSUB-FEATURES ::= '=' FEATURE-LIST ?
 273
 274   GPOS-FEATURES ::= '+' FEATURE-LIST ?
 275
 276   FEATURE-LIST ::= ( SYMBOL ',' ) * [ SYMBOL | '*' ]
 277
 278 @endverbatim
 279
 280 Each @c SYMBOL specifies a tag name defined in the OpenType
 281 specification.
 282
 283 For @c SCRIPT, @c SYMBOL specifies a Script tag name (e.g. deva for
 284 Devanagari).
 285
 286 For @c LANGSYS, @c SYMBOL specifies a Language System tag name.  If @c
 287 LANGSYS is omitted, the Default Language System
 288 table is used.
 289
 290 For @c GSUB-FEATURES, each @c SYMBOL specifies a GSUB Feature tag name
 291 to apply.  '*' is allowed as the last item to specify all remaining
 292 features.  If @c SYMBOL is preceded by '~' and the last item is '*',
 293 @c SYMBOL is excluded from the features to apply.  If no @c SYMBOL is
 294 specified, no GSUB feature is applied.  If @c GSUB-FEATURES itself is
 295 omitted, all GSUB features are applied.
 296
 297 The specification of @c GPOS-FEATURES is analogous to that of @c
 298 GSUB-FEATURES.
 299
 300 See the following page for the OpenType specification.\n
 301     <http://www.microsoft.com/typography/otspec/default.htm>
 302
 303 @verbatim
 304 COMBINING ::= SYMBOL
 305 @endverbatim
 306
 307 @c COMBINING is a symbol whose name specifies how
 308 to combine the next glyph with the previous one.  This rule sets the
 309 default combining-spec to an integer code that is unique to the symbol
 310 name.  The name has the following syntax.
 311
 312 @verbatim
 313   COMBINING-NAME ::= VPOS HPOS OFFSET VPOS HPOS
 314
 315   VPOS ::= 't' | 'c' | 'b' | 'B'
 316
 317   HPOS ::= 'l' | 'c' | 'r'
 318
 319   OFFSET :: = '.' | XOFF | YOFF XOFF ?
 320
 321   XOFF ::= ('<' | '>') INTEGER ?
 322
 323   YOFF ::= ('+' | '-') INTEGER ?
 324 @endverbatim
 325
 326 @c VPOS and @c HPOS specify the vertical and horizontal positions
 327 as described below.
 328
 329 @verbatim
 330                                 POINT VPOS HPOS
 331                                 ----- ---- ----
 332     0----1----2 <---- top       0     t    l
 333     |         |                 1     t    c
 334     |         |                 2     t    r
 335     |         |                 3     B    l
 336     9   10   11 <---- center    4     B    c
 337     |         |                 5     B    r
 338   --3----4----5-- <-- baseline  6     b    l
 339     |         |                 7     b    c
 340     6----7----8 <---- bottom    8     b    r
 341                                 9     c    l
 342     |    |    |                10     c    c
 343   left center right            11     c    r
 344 @endverbatim
 345
 346 The left figure shows 12 reference points of a glyph by numbers 0 to
 347 11.  The rectangle 0-6-8-2 is the bounding box of the glyph, the
 348 positions 3, 4, and 5 are on the baseline, 9 and 11 are on the center
 349 of the lines 0-6 and 2-8 respectively, 1, 10, 4, and 7 are on the
 350 center of the lines 1-2, 3-5, 9-11, and 6-8 respectively.
 351
 352 The right table shows how those reference points are specified by a
 353 pair of @c VPOS and @c HPOS.
 354
 355 The first @c VPOS and @c HPOS in the definition of @c COMBINING-NAME
 356 specify the
 357 reference point of the previous glyph, and the second @c VPOS and @c
 358 HPOS specify that of the next glyph.
 359 The next glyph is drawn so that these two reference points align.
 360
 361 @c OFFSET specifies the way of alignment in detail.  If it is '.', the
 362 reference points are on the same position.
 363
 364 @c XOFF specifies how much the X position of the next reference point
 365 should be shifted to the right ('<') or left ('>') from the previous
 366 reference point.
 367
 368 @c YOFF specifies how much the Y position of the next reference point
 369 should be shifted upward ('+') or downward ('-') from the previous reference
 370 point.
 371
 372 In both cases, @c INTEGER is the amount of shift expressed as a
 373 percentage of the font size, i.e., if @c INTEGER is 10, it means
 374 10% (1/10) of the font size.  If @c INTEGER is omitted, it is assumed that
 375 5 is specified.
 376
 377 Once the next glyph is combined with the previous one, they
 378 are treated as a single combined glyph.
 379
 380 @verbatim
 381 MACRO-NAME ::= SYMBOL
 382 @endverbatim
 383
 384 @c MACRO-NAME is a symbol that appears in one of @c MACRO-DEF.  It is
 385 exapanded to the sequence of the correponding @c RULSs.
 386
 387 @section flt-context-dependent CONTEXT DEPENDENT BEHAVIOR
 388
 389 So far, it has been assumed that each sequence, which is drawn with a
 390 specific font, is context free, i.e. not affected by the glyphs
 391 preceding or following that sequence.  This is true when sequence S1
 392 is drawn with font F1 while the preceding sequence S0 unconditionally
 393 requires font F0.
 394
 395 @verbatim
 396   sequence                              S0      S1
 397   currently used font                   F0      F1
 398   usable font(s)                        F0      F1
 399 @endverbatim
 400
 401 Sometimes, however, a clear separation of sequences is not possible.
 402 Suppose that the preceding sequence S0 can be drawn not only with F0
 403 but also with F1.
 404
 405 @verbatim
 406   sequence                              S0      S1
 407   currently used font                   F0      F1
 408   usable font(s)                        F0,F1   F1
 409 @endverbatim
 410
 411 In this case, glyphs used to draw the preceding S0 may affect glyph
 412 generation of S1.  Therefore it is necessary to access information
 413 about S0, which has already been processed, when processing S1.
 414 Generation rules in the first stage (only in the first stage) accept a
 415 special regular expression to access already processed parts.
 416
 417 @verbatim
 418   "RE0 RE1"
 419 @endverbatim
 420
 421 @c RE0 and @c RE1 are regular expressions that match the preceding
 422 sequence S0 and the following sequence S1, respectively.
 423
 424 Pay attention to the space between the two regular expressions.  It
 425 represents the special category ' ' (see above).  Note that the
 426 regular expression above belongs to glyph generation rules using font
 427 F1, therefore not only RE1 but also RE0 must be expressed with the
 428 categories for F1.  This means when the preceding sequence S0 cannot
 429 be expressed with the categories for F1 (as in the first example
 430 above) generation rules having these patterns never match.
 431
 432 @section flt-seealso SEE ALSO
 433
 434 @ref mdbGeneral "mdbGeneral(5)",
 435 @ref flt-list "FLTs provided by the m17n database"
 436 */
 437
 438 /*
 439 Copyright (C) 2003, 2004
 440   National Institute of Advanced Industrial Science and Technology (AIST)
 441   Registration Number H15PRO112
 442
 443 This file is part of the m17n database; a sub-part of the m17n
 444 library.
 445
 446 The m17n library is free software; you can redistribute it and/or
 447 modify it under the terms of the GNU Lesser General Public License
 448 as published by the Free Software Foundation; either version 2.1 of
 449 the License, or (at your option) any later version.
 450
 451 The m17n library is distributed in the hope that it will be useful,
 452 but WITHOUT ANY WARRANTY; without even the implied warranty of
 453 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 454 Lesser General Public License for more details.
 455
 456 You should have received a copy of the GNU Lesser General Public
 457 License along with the m17n library; if not, write to the Free
 458 Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
 459 02111-1307, USA.
 460 */