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