diff options
| -rw-r--r-- | DESIGN | 199 | ||||
| -rw-r--r-- | README | 85 | ||||
| -rw-r--r-- | TODO | 1 |
3 files changed, 285 insertions, 0 deletions
@@ -0,0 +1,199 @@ +In implementing the Metro parser on top of Fitz, and with the new +road map, I am facing the task of designing the API for managing +resources in Fitz. Up till now I have punted on making any final +decisions, exploring as I go. Now I feel that I cannot do so much longer. +Therefore I would like to hear your opinions and ideas on this. +Please brainstorm and point out any missing pieces. + +First, a ten mile high overview of the Fitz architecture and +nomenclature, for those of you who are not in the loop or need +a refresher :) + +The Fitz world is a set of resources. There are many kinds of resources. +Resources can depend on other resources, but no circular dependencies. +The resource types are: tree, font, image, shade, and colorspace. +A document is a sequence of tree resources that define the contents +of its pages. + +A front-end is a producer of Fitz worlds, that reads a file and +creates a Fitz world from its contents. Abstracting this into +a high-level interface is useful primarily for viewers and +converters. + +A back-end is a consumer of Fitz worlds. The default rasterizer +is one back-end. PDF writers and other output drivers too. +I don't think there should be a special interface for these. +They are just functions or programs that take the Fitz world +and do something unspecified with it. + +The resource API is what I need help fleshing out. Keep in mind +that a Fitz world should be able to be serialized to disk, so having +callbacks and other hooks into the front-end is a no no. If it weren't +for this, my life would be a lot simpler :) + +Both creation, querying, and on-disk format. + +-------------------------------------------------------------------- + +TREE + +The Fitz tree resource is the primary data structure. +A tree consists of nodes. There are leaf nodes and branch +nodes. Leaf nodes produce images, branch nodes combine +or change images. An image here is a two-dimensional +region of color and shape (alpha). + +LEAF NODES + +SOLID. +A constant color or shape that stretches out to infinity. + +IMAGE. +A rectangular region of color and or shape derived +a from a grid of samples. +Outside this rectangle is transparent. +References an image resource. + +SHADE. +A mesh of patches that define a region of interpolated colors. +Outside the mesh is transparent. +References a shade resource. + +PATH. +A path defines only shape. +Moveto, lineto, curveto and closepath. +Stroke, fill, even-odd-fill. +Dash patterns. + +TEXT. +A text node is an optimization, space-effectively combining +a transform matrix and references to glyph shapes. +Text nodes define only shape. + +Text nodes have a b c d coefficients and a reference to a font. +Then an array of glyph index and e and f coefficient tuples. + +Text nodes may also have a separate unicode array, +associating the (glyph,e,f) tuples with unicode character codes. +One-to-many and many-to-one mappings are allowed. +For text search and copy. + +BRANCH NODES + +TRANSFORM. +Transform nodes apply an affine transform matrix to +its one and only child. + +OVER. +An over node stacks its children on top of each other, +combining their colors with a blending mode. + +MASK. +A mask node has two children. The second child is masked +with the first child, multiplying their shapes. +This causes the effect of clipping. + +(mask + (path ...) + (solid 'devicegray 0)) + +BLEND. +This does the magic of PDF 1.4 transparency. +The isolated and non-isolated and +knockout group stuff happens here. +It also sets the blend mode for its children. + +LINK. +This is a dummy node that grafts in another +tree resource. The effect is as if the other +tree was copied here instead. +References a tree resource. + +META. +A way to insert application specific data. +Transparent to the rasterizer, but can be +useful to preserve some non-Fitz semantics +that may be of use to specific producers/consumers +of Fitz trees. For example, tiling patterns +would be represented as an over node with +many transform and link nodes stamping out +the pattern to fill the page. Putting these +under an appropriate Meta node would allow +a PDF or Postscript backend to detect and +recreate the tiling pattern. + +(meta 'pattern "...tiling pattern info..." + (over + (transform 1 0 0 1 0 0 (link 'pat1)) + (transform 1 0 0 1 0 1 (link 'pat1)) + (transform 1 0 0 1 1 0 (link 'pat1)) + (transform 1 0 0 1 1 1 (link 'pat1)))) + +-------------------------------------------------------------------- + +COLORSPACES. + +A colorspace needs the capability to transform colors into +and out of any other colorspace. I suggest that this happens +by going either through a standard colorspace (CIE XYZ), +or by having an optional A-to-B shortcut transform. + +I am thinking of three sub-classes: + + Device colors. Fast and dirty: Gray, RGB, CMYK only. + + ICC Profiles. I am not very familiar with this. + Use Argyll? Are they easy to create programmatically + to represent the Cal* and L*a*b colorspaces? + + Separation. For Separation and DeviceN. + This is a list of named colors, with backend + specific tailoring required to make sense of it. Also has + an alternate colorspace (Device or ICC) with a transform. + How do we represent the transform function? + +SHADES. + +This is fairly simple. A mesh of patches as in PDF. +Three levels of detail: with full tensors, with only patches, +with linear quads. Axial and radial shadings are trivially +converted. Type 1 (functional) shadings need to be sampled. + +If the backends cannot cope, it can either convert to +linear shaded triangles (clip an axial shading with a triangular +path) or render to an image. + +FONTS. + +There need to be four types of font resources. +For now I am going to use FreeType, but that should not be a necessity. +The resource format for fonts should be independent. + + * Fake fonts for substituted fonts. Refer to another fall-back + font resource and override the metrics. + Could possibly be represented as a type 3 font, + but knowing that it is a substitute may be useful. + + * Type 3 fonts where each glyph is represented as a Fitz tree resource. + + * Postscript fonts, in CFF format. + Type 1 and Type 1 CID fonts are losslessly convertible to CFF. + OpenType fonts can have CFF glyph data. + + * TrueType fonts + +IMAGES. + +This is the tricky one. Raph, I forgot what we decided on the tiling. +What size, planar or chunky, etc. Which bit depths do we allow? +Image data should be chopped into tiles to allow for independent +and random access and more CPU-cache friendly image scaling and +color transforms. + + * JPEG encoded images. + Save byte+bit offsets to allow random access to groups of eight scanlines. + * Monochrome images. + * Contone images. + +The End + @@ -0,0 +1,85 @@ +README for the Fitz distribution. + +Fitz is a graphics library. +MuPDF is a PDF parsing and manipulation library. +Samus is a Metro parser. +GhostPDF is a PDF viewer using MuPDF and Fitz. +For Windows, there is also a Mozilla plugin version of the viewer. + +GhostPDF has three ports: X11, Windows and Carbon. +The Carbon port is broken, so don't bother trying it. + +This code is under the same licensing scheme as Ghostscript. +AFPL and one year or major release later GPL. +Because there have been no major releases yet; AFPL it is. + +PREREQUISITES + +Before compiling Fitz you need to install thirdy party dependencies. + + zlib + libjpeg + libpng + freetype2 + expat + +There are a few optional dependencies that you don't strictly need. +You will probably want the versions that Ghostscript maintains. + + jbig2dec + jasper + +Fitz uses the Perforce Jam build tool. You need the Perforce version 2.5 +or later. Earlier versions (including the FTJam fork) have crippling bugs. +Boost Jam is not backwards compatible. If you do not have a compiled +binary for your system, you can find the Jam homepage here: + + http://www.perforce.com/jam/jam.html + +The build also uses 'xxd', a hexdump tool that ships with Vim. +Here's a copy of the source if it's not on your system: + + http://ghostscript.com/~tor/download/xxd.c + +I use Mingw and MSYS to compile for Windows. If you use anything +else, you are on your own. + +COMPILING + +If all of that is installed, compiling should be a cinch. +Issue the command 'jam' in the root of the Fitz directory. +Add a parameter '-sBUILD=release' or '-sBUILD=profile' to +build release or profile versions. + + $ jam '-sBUILD=release' + +If the build fails because it cannot find header files or libraries, +look first in Jamrules to see if there is anything wrong with the +search paths or compiler flags for your system. + +To compile in the optional jbig2 and jpeg2000 support, you need +to add the following arguments to jam: + + $ jam '-sHAVE_JBIG2DEC=yes' '-sHAVE_JASPER=yes' + +To build the X11 version under MacOS X, add: + + $ jam '-sHAVE_X11=yes' + +INSTALLING + +There is no install. The command "jam install" will copy the +compiled binaries (for the specified build -- debug, release or profile) +into a "dist/" directory. + +There is no support for building a shared library. + +REPORTING BUGS AND PROBLEMS + +Send reports to tor@ghostscript.com. + +If you are reporting a problem with PDF parsing, +please include the problematic file as an attachment. + +-- tor + @@ -107,6 +107,7 @@ Shades: Fonts: fz_font + fz_fakefont # substitute fonts fz_t3font # sub-trees define glyphs fz_psfont # cff postscript font fz_ttfont # truetype font |