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.
|