This package and its subpackages contain classes that represent individual fonts.

Implementations of {@link com.adobe.fontengine.font.Font Font} provide client access to basic font functionality. This includes access to data used to generate pdfs.

The following font formats are supported:

How to Generate PDF Font objects.

AFE provides access to information that helps create PDF Font objects, PDF Font Descriptor objects, and PDF font streams. In particular, {@link com.adobe.fontengine.font.Font#getPDFFontDescription Font.getPDFFontDescription} can be used to fetch a {@link com.adobe.fontengine.font.PDFFontDescription PDFFontDescription}, which returns names and metrics that are needed to build these objects.

AFE interprets embedding permissions for its clients, but it does NOT perform gatekeeping. That is, it does not prevent clients from embedding fonts which they must not embed. The current AFE API only exposes whether a font can be used for print-and-preview use. If other uses are required, the AFE API will need to be expanded. Clients can determine if fonts are allowed to be embedded for print-and-preview use by calling {@link com.adobe.fontengine.font.Font#canEmbedForPrintAndPreview Font.canEmbedForPrintAndPreview}. If this method returns true, print-and-preview clients can call {@link com.adobe.fontengine.font.Font#subsetAndStream Font.subsetAndStream} to embed fonts. If it returns false, clients MUST NOT embed the font. When {@link com.adobe.fontengine.font.Font#subsetAndStream Font.subsetAndStream} generates fonts to be put in a PDF Font Stream, it generates fonts appropriate for use in PDF Composite fonts.

How to Generate PDF Content streams and encodings with embedded fonts.

The most reliable PDFs are those that contain all of the fonts used. For this reason, when allowed, clients should embed fonts. In that case, an Identity-H encoding must be used unless {@link com.adobe.fontengine.font.PDFFontDescription#getROS PDFFontDescription.getROS} returns non-null. Even in that case, Identity-H can be used and is generally the easiest encoding to use. If getROS returns null, the codepoints used in the content stream must be the subset glyphIDs (returned from {@link com.adobe.fontengine.font.Subset#getSubsetGid Subset.getSubsetGid}). If getROS returns non-null, the codepoints will depend on the setting of the preserveROS parameter to {@link com.adobe.fontengine.font.Font#subsetAndStream Font.subsetAndStream}.

How to Generate PDF Content streams and encodings with unembedded fonts.

When fonts can't be embedded, generating encodings is much more difficult. If {@link com.adobe.fontengine.font.PDFFontDescription#getROS PDFFontDescription.getROS} returns non-null, composite fonts must be created and Identity-H can be used safely. In that case, codepoints must be CIDs in the ROS returned. {@link com.adobe.fontengine.font.PDFFontDescription#getGlyphCid PDFFontDescription.getGlyphCid} returns CIDs in this case.

In all other cases, Identity-H can not be used portably. In those cases, if {@link com.adobe.fontengine.font.PDFFontDescription#pdfFontIsTrueType PDFFontDescription.pdfFontIsTrueType} returns false, a simple font must be created. {@link com.adobe.fontengine.font.PDFFontDescription#getGlyphName PDFFontDescription.getGlyphName} will always return a valid name. Those names should be used to build up the encoding.

If {@link com.adobe.fontengine.font.PDFFontDescription#pdfFontIsTrueType PDFFontDescription.pdfFontIsTrueType} returns true, generating encodings is more complicated. The following algorithm is one possible way encodings can be generated:

  1. Fetch all of the glyph names for the glyphs in the subset using {@link com.adobe.fontengine.font.PDFFontDescription#getGlyphName PDFFontDescription.getGlyphName}.
  2. If all of the glyph names are in winansi or macroman, simple fonts can be created using the enclosing encoding.
  3. Otherwise, a {@link com.adobe.fontengine.font.PDFEncodingBuilder} can be created. If it returns a non-null encoding from {@link com.adobe.fontengine.font.PDFEncodingBuilder#getEncoding PDFEncodingBuilder.getEncoding} for every glyph in the subset, then one or more composite fonts can be created (one for each unique encoding returned from {@link com.adobe.fontengine.font.PDFEncodingBuilder#getEncoding PDFEncodingBuilder.getEncoding}). The returned encodings can be mapped to CMaps that can be used as encodings for the composite fonts. If a given CMap is not allowed to be used because it is not compatible with the pdf version being generated, the client can attempt to convert encodings. If a given glyph either does not have an associated encoding or if it has an encoding but that encoding is not acceptable and attempts to translate fail, the client should go to the next step. Otherwise, composite fonts are ideal and should be used.
  4. Otherwise, if all of the glyphs have names according to {@link com.adobe.fontengine.font.PDFFontDescription#getGlyphName PDFFontDescription.getGlyphName}, a simple font should be created and a differences array built.
  5. Otherwise, a completely portable pdf cannot be created. Glyphs that can be covered by one of the above steps should be handled in that way. For the remaining glyphs, an identity encoding is the best that can be done. This pdf will not work if the exact font is not available to the rendering software.