{ "content": [ { "type": "text", "text": "# Font::TTF::Manual (perldoc)\n\n## NAME\n\nFont::TTF::Manual - Information regarding the whole module set\n\n## Sections\n\n- **NAME**\n- **INTRODUCTION** (2 subsections)\n- **METHODS** (1 subsections)\n- **AUTHOR**\n- **LICENSING**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "Font::TTF::Manual", "section": "", "mode": "perldoc", "summary": "Font::TTF::Manual - Information regarding the whole module set", "synopsis": null, "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [], "examples": [], "see_also": [], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "INTRODUCTION", "lines": 22, "subsections": [ { "name": "Design Principles", "lines": 30 }, { "name": "Conventions", "lines": 7 } ] }, { "name": "METHODS", "lines": 89, "subsections": [ { "name": "Creating fonts", "lines": 21 } ] }, { "name": "AUTHOR", "lines": 2, "subsections": [] }, { "name": "LICENSING", "lines": 5, "subsections": [] } ], "sections": { "NAME": { "content": "Font::TTF::Manual - Information regarding the whole module set\n", "subsections": [] }, "INTRODUCTION": { "content": "This document looks at the whole issue of how the various modules in the TrueType Font work\ntogether. As such it is partly information on this font system and partly information on\nTrueType fonts in general.\n\nDue to the inter-relation between so many tables in a TrueType font, different tables will make\nexpectations as to which other tables exist. At the very least a font should consist of a \"head\"\ntable and a \"maxp\" table. The system has been designed around the expectation that the necessary\ntables for font rendering in the Windows environment exist. But inter table dependencies have\nbeen kept to what are considered necessary.\n\nThis module set is not meant as a simple to use, mindless, font editing suite, but as a\nlow-level, get your hands dirty, know what you are doing, set of classes for those who\nunderstand the intricacies (and there are many) of TrueType fonts. To this end, if you get\nsomething wrong in the data structures, etc. then this module set won't tell you and will\nhappily create fonts which don't work.\n\nAt the time of writing, not every TrueType table in existence has been implemented! Only the\ncore basic tables of TrueType 1.0 (i.e. no embedded bitmap tables, no postscript type tables, no\nOpenType tables and no GX tables) have been implemented. If you want to help by implementing\nanother table or two, then please go ahead and send me your code. For a full list of tables, see\nFont::TTF::Font.\n", "subsections": [ { "name": "Design Principles", "content": "PERL is not C++. C++ encourages methods to be written for changing and reading each instance\nvariable in a class. If we did this in this PERL program the results would be rather large and\nslow. Instead, since most access will be read access, we expose as much of the inner storage of\nan object to user access directly via hash lookup. The advantage this gives are great. For\nexample, by following an instance variable chain, looking up the \"yMax\" parameter for a\nparticular glyph becomes:\n\n$f->{'loca'}{'glyphs'}[$glyph]{'yMax'}\n\nOr, if we are feeling very lazy and don't mind waiting:\n\n$f->{'loca'}{'glyphs'}[$f->{'cmap'}->mslookup(0x41)]{'yMax'}\n\nThe disadvantage of this method is that it behoves module users to behave themselves. Thus it\ndoes not hold your hand and ensure that if you make a change to a table, that the table is\nmarked as *dirty*, or that other tables are updated accordingly.\n\nIt is up to the application developer to understand the implications of the changes they make to\na font, and to take the necessary action to ensure that the data they get out is what they want.\nThus, you could go and change the \"yMax\" value on a glyph and output a new font with this\nchange, but it is up to you to ensure that the font's bounding box details in the \"head\" table\nare correct, and even that your changing \"yMax\" is well motivated.\n\nTo help with using the system, each module (or table) will not only describe the methods it\nsupports, which are relatively few, but also the instance variables it supports, which are many.\nMost of the variables directly reflect table attributes as specified in the OpenType\nspecification, available from Microsoft (), Adobe and\nApple. A list of the names used is also given in each module, but not necessarily with any\nfurther description. After all, this code is not a TrueType manual as well!\n" }, { "name": "Conventions", "content": "There are various conventions used in this system.\n\nFirstly we consider the documentation conventions regarding instance variables. Each instance\nvariable is marked indicating whether it is a (P)rivate variable which users of the module are\nnot expected to read and certainly not write to or a (R)ead only variable which users may well\nwant to read but not write to.\n" } ] }, "METHODS": { "content": "This section examines various methods and how the various modules work with these methods.\n\nread and readdat\nBefore the data structures for a table can be accessed, they need to be filled in from\nsomewhere. The usual way to do this is to read an existing TrueType font. This may be achieved\nby:\n\n$f = Font::TTF::Font->open($filename) || die \"Unable to read $filename\";\n\nThis will open an existing font and read its directory header. Notice that at this point, none\nof the tables in the font have been read. (Actually, the \"head\" and \"maxp\" tables are read at\nthis point too since they contain the commonly required parameters of):\n\n$f->{'head'}{'unitsPerEm'}\n$f->{'maxp'}{'numGlyphs'}\n\nIn order to be able to access information from a table, it is first necessary to \"read\" it.\nConsider trying to find the advance width of a space character (U+0020). The following code\nshould do it:\n\n$f = Font::TTF::Font->open($ARGV[0]);\n$snum = $f->{'cmap'}->mslookup(0x0020);\n$sadv = $f->{'hmtx'}{'advance'}[$snum];\nprint $sadv;\n\nThis would result in the value zero being printed, which is far from correct. But why? The first\nline would correctly read the font directory. The second line would, incidently, correctly\nlocate the space character in the Windows cmap (assuming a non symbol encoded font). The third\nline would not succeed in its task since the \"hmtx\" table has not been filled in from the font\nfile. To achieve what we want we would first need to cause it to be read:\n\n$f->{'hmtx'}->read;\n$sadv = $f->{'hmtx'}{'advance'}[$snum];\n\nOr for those who are too lazy to write multiple lines, \"read\" returns the object it reads. Thus\nwe could write:\n\n$sadv = $f->{'hmtx'}->read->{'advance'}[$snum];\n\nWhy, if we always have to read tables before accessing information from them, did we not have to\ndo this for the \"cmap\" table? The answer lies in the method call. It senses that the table\nhasn't been read and reads it for us. This will generally happen with all method calls, it is\nonly when we do direct data access that we have to take the responsibility to read the table\nfirst.\n\nReading a table does not necessarily result in all the data being placed into internal data\nstructures. In the case of a simple table \"read\" is sufficient. In fact, the normal case is that\n\"readdat\" reads the data from the file into an instance variable called ' dat' (including the\nspace) and not into the data structures.\n\nThis is true except for the \"glyph\" class which represents a single glyph. Here the process is\nreversed. Reading a \"glyph\" reads the data for the glyph into the ' dat' instance variable and\nsets various header attributes for the glyph (\"xMin\", \"numContours\", etc.). The data is\nconverted out of the variable into data structures via the \"readdat\" method.\n\nThe aim, therefore, is that \"read\" should do the natural thing (read into data structures for\nthose tables and elements for which it is helpful -- all except \"glyph\" at present) and\n\"readdat\" should do the unnatural thing: read just the binary data for normal tables and\nconvert binary data to data structures for \"glyph\"s.\n\nIn summary, therefore, use \"read\" unless you want to hack around with the internals of glyphs in\nwhich case see Font::TTF::Glyph for more details.\n\nupdate\nThe aim of this method is to allow the various data elements in a \"read\" font to update\nthemselves. All tables know how to update themselves. All tables also contain information which\ncannot be *updated* but is new knowledge in the font. As a result, certain tables do nothing\nwhen they are updated. We can, therefore, build an update hierarchy of tables, with the\nindependent tables at the bottom and \"Font\" at the top:\n\n+--loca\n|\nglyf--+--maxp\n|\n+---+--head\n|\nhmtx------+--hhea\n\ncmap-----OS/2\n\nname--\n\npost--\nThere is an important universal dependency which it is up to the user to\nkeep up to date. This is C which is used to iterate over all\nthe glyphs. Note that the glyphs themselves are not held in the C table\nbut in the C table, so adding glyphs, etc. automatically involves keeping\nthe C table up to date.\n", "subsections": [ { "name": "Creating fonts", "content": "Suppose we were creating a font from scratch. How much information do we need to supply and how\nmuch will \"update\" do for us?\n\nThe following information is required:\n\n$f->{'loca'}{'glyphs'}\n$f->{'head'}{'upem'}\n$f->{'maxp'}{'numGlyphs'} (doesn't come from $f->{'loca'}{'glyphs'})\n$f->{'hmtx'}{'advance'}\n$f->{'post'}['format'}\n$f->{'post'}{'VAL'}\n$f->{'cmap'}\n$f->{'name'}\n\nPretty much everything else is calculated for you. Details of what is needed for a glyph may be\nfound in Font::TTF::Glyph. Once we have all the information we need (and there is lots more that\nyou could add) then we simply\n\n$f->dirty; # mark all tables dirty\n$f->update; # update the font\n" } ] }, "AUTHOR": { "content": "Martin Hosken . (see CONTRIBUTORS for other authors).\n", "subsections": [] }, "LICENSING": { "content": "Copyright (c) 1998-2016, SIL International (http://www.sil.org)\n\nThis module is released under the terms of the Artistic License 2.0. For details, see the full\ntext of the license in the file LICENSE.\n", "subsections": [] } } } }