Meta Image Application Programming Interfaces

The following APIs are ones that deal with the conversion of meta images (ie WMF or EMF images).

If possible try converting a meta image to native PDF commands (using I2PDF_MetaToNativePDF below). This gives much better quality and a smaller PDF size too. However, it is not possible to convert all possible meta image commands into native PDF equivalent commands so the conversion may not be 100% accurate.

If you do not convert to native PDF then a meta image is rendered into an image bitmap using Windows to perform the rendering. This results in a non-scalable and larger sized PDF but should be a pretty accurate conversion (using I2PDF_MetaImageMaxMP and associated commands).

Font Support

All TrueType fonts which have a Unicode CMAP font resource (which defines the names of the glyphs available) within their font definition can be used successfully within the "native" PDF conversion. If a font that is used within a meta image cannot be used then a default font is substituted (see I2PDF_MetaDefaultFont).

It is not possible to convert all Unicode characters that may be used, but the ones in the following Unicode codepages are mostly supported: CP874 (Thai), CP1250 (Latin2), CP1251 (Cyrillic), CP1252 (Latin1), CP1253 (Greek), CP1254 (Turkish), CP1255 (Hebrew), CP1256 (Arabic), CP127 (Baltic).

Additionally, Arabic contextual forms (initial, medial, final and isolated) are supported through the use of the I2PDF_UseArabicContextualForms API.

  I2PDF_MetaToNativePDF
Parameters: None
Return Value: None
Notes:
  • Converts a meta image file into a native PDF representation (does not render into an image but converts meta image commands directly into equivalent native PDF graphic and text functions).
  • Note: This may not be a perfect representation as there are features of meta image files that just cannot be duplicated using the native PDF facilities. However the PDF files produced are much smaller in filesize and usually of higher quality too.

  •   I2PDF_CenterMetaImageOnPage
    Parameters: None
    Notes:
  • Rather than using a manual combination of I2PDF_MetaMargins and I2PDF_SetBorder APIs to try and get a native rendered page to have the contents centered on the page, this API will perform this automatically based on the content of the meta image that is actually rendered into the PDF.

  •   I2PDF_MetaTextFitBoundingRect
    Parameters: None
    Return Value: None
    Notes:
  • If text in a meta image file is larger than the defined bounding rectangle this command will progressively reduce the font size until it can fit the text within the defined bounding area.
  • Depending on the composition of your meta image file it is sometimes better (with the text being more legible) if the text is allowed to extend outside the defined bounding rectangle (as long as there is nothing immediately next to it of course).
  • Note: This only works if I2PDF_MetaToNativePDF has been used.

  •   I2PDF_MetaMargins
    Parameters: None
    Return Value: None
    Notes:
  • By default a meta image file is rendered as an image that is just large enough to enclose it. This API overrides this behaviour for those situations where you want to preserve the margins around the image (no matter how large they might be).

  •   I2PDF_UseEMFDeviceSize
    Parameters: None
    Return Value: None
    Notes:
  • By default the dimensions (ie size) of an EMF image is determined by using the declared bounding rectangle which is stored as part of the meta file. Sometimes (and this depends on the application that created it) this can lead to a distorted (ie incorrectly sized) image. If this appears to be the case then try using this command which ignores the declared bounding rectangle and uses the declared reference device pixel size (again some applications may not set this correctly - although one would hope that at least one of these three - see also I2PDF_UseEMFFrameSize - settings has been correctly set!).

  •   I2PDF_UseEMFFrameSize
    Parameters: None
    Return Value: None
    Notes:
  • By default the dimensions (ie size) of an EMF image is determined by using the declared bounding rectangle which is stored as part of the meta file. Sometimes (and this depends on the application that created it) this can lead to a distorted (ie incorrectly sized) image. If this appears to be the case then try using this command which ignores the declared bounding rectangle and uses the declared frame size in millimeters which is converted into a pixel size (again some applications may not set this correctly - although one would hope that at least one of these three - see also I2PDF_UseEMFDeviceSize - settings has been correctly set!).

  •   I2PDF_MetaDefaultFont
    Parameters: font name - must be one of the following standard PDF fonts:
  • Courier
  • Courier-Bold
  • Courier-BoldOblique
  • Courier-Oblique
  • Helvetica
  • Helvetica-Bold
  • Helvetica-BoldOblique
  • Helvetica-Oblique
  • Times-Roman
  • Times-Bold
  • Times-Italic
  • Times-BoldItalic
  • Return Value: 0 - success
    1 - invalid font name
    Notes:
  • If a font cannot be matched then this allows the specification of one of the standard PDF fonts to be used.
  • If this is not specified then a default Helvetica font is used if the original font was determined as being of a proportional type or a default of Courier is used if it was determined as being of a mono-spaced type.

  •   I2PDF_MetaToNativeFontSubstitution
    I2PDF_MetaToNativeFontSubs
    Parameters: substitution description - text (up to 500 characters) specifying the font and character(s) substitution as follows:
    <original font name>=<substitute font name>:<original character code>=<substitute character code>{,<original character code>=<substitute character code>}
    <original character code> can be an ASCII code (32 to 255) or Unicode code or a ? (which matches all characters not substituted)
    <substitute character code> must be an ASCII code (32 to 255) - the character output is the code in the font specified (which is not necessarily a letter but could be a symbol)
    Return Value: 0 - success
    1 - invalid substitution description
    2 - maximum number of substitution strings already defined
    Notes:
  • This API can only be used in conjunction with the I2PDF_MetaToNativePDF API.
  • If a font cannot be matched (perhaps because it is not a True Type font with a CMAP record) then this allows an alternative font and specific character substitutions to be made.
  • This is commonly used to substitute non-textual (symbolic) fonts, for example WingDings (click here for a list of the glyphs in the various WingDings fonts and to see the list of available ZapgDingbats glyphs).
  • You can specify multiple character substitutions by separating the <original character code>=<substitute character code> mappings with commas.
  • Up to 100 substitution strings can be setup and they are processed for a match in the order that they are defined.
  • You cannot specify different font substitutions for the same font - ie if you define that WingDings is substituted for ZapfDingbats you cannot also define that WingDings is substituted for another font.
  • A non-standard font, such as WingDings, is normally recorded in unicode as being in the Private Use Area (PUA) range of codes which are from F000 to F0FF (in hexadecimal). When specifying the substitutions you do not specify the full PUA code but just the actual character code from 0 to 255.

  •   I2PDF_MetaDefaultFontXScaling
    Parameters: scale factor - a numeric value that must be between 0.01 and 100.0 inclusive.
    Return Value: 0 - success
    1 - invalid scale factor
    Notes:
  • This API can only be used in conjunction with the I2PDF_MetaDefaultFont API.
  • If a font cannot be matched (perhaps because it is not a True Type font with a CMAP record) then this allows the arbitrary scaling of the width of the font in order to better match the actual physical dimensions of the substituted font.

  •   I2PDF_UseArabicContextualForms
    I2PDF_UseArabicContextForms
    Parameters: None
    Return Value: None
    Notes:
  • This API can only be used in conjunction with the I2PDF_MetaDefaultFont API.
  • By default, when Arabic Unicode text is used (codepage CP1256) the Arabic glyphs do not take into account the context and relationship with other Arabic and non-Arabic text. This command will enable the analysis of the surrounding text in order to change the glyph to one of the contextual Arabic alternatives (known as initial, medial, final and isolated forms).
  • It should be noted that not all available Arabic supporting fonts have all of the required Arabic contextual form characters, and therefore the output will feature non-available glyphs (shown as an outlined rectangular shape).

  •   I2PDF_EmbedFonts
    Parameters: None
    Return Value: None
    Notes:
  • This API can only be used in conjunction with the I2PDF_MetaDefaultFont API.
  • If a document is converted which uses an unusual font that is not likely to be installed on a target system then this command will ensure that all of the font details are embedded within the PDF so that the target system that a PDF may be viewed on does not require the font in order to display the text within the PDF correctly.
  • It should be noted that this will increase the file size of the produced PDF - but that may be a small price to pay to ensure that all users can view the PDF correctly.