Meta Image (Bitmap) 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 and associated commands). 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.

  I2PDF_MetaImageMaxMP
Parameters: max megapixel size - specifies the meta image (EMF or WMF) maximum rendering size and must be a value between 0.1 and 20.0 inclusive.
Return Value: 0 - success
1 - invalid max megapixel size parameter
Notes:
  • Meta image files can often be authored at very high resolutions (sometimes in excess of 10,000 units for both the width and height) and this would lead to very large converted image sizes. To combat this it is possible to set the maximum total area of the rendered image as a value in megapixels (similar to the way that digital cameras have their resolutions quoted). If a meta image file's width x height is greater than the specified number of mega pixels then it is re-sized to be within this value. It is important to note that this "re-size" is actually a meta image file rendering transformation and not a "re-size" in the strictest sense (see the I2PDF_MetaImageScale API below for this option).
  • Here is a list of common mega pixel sizes and an example of an image size that just fits within this limit:
  • 1.3 = 1300 x 1000
    2.2 = 1800 x 1200
    3.1 = 2000 x 1600
    4.3 = 2400 x 1800
    5.3 = 2700 x 2000
    6.1 = 2900 x 2200
    8.2 = 3400 x 2500
    10.0 = 3700 x 2800
  • The default setting is 2.2

  •   I2PDF_MetaImageMaxMP_Int
    Parameters: max megapixel size - specifies the meta image (EMF or WMF) maximum rendering size and must be a value between 1 and 200 inclusive (this is divided by 10 internally to give a value between 0.1 and 20.0).
    Return Value: 0 - success
    1 - invalid max megapixel size parameter
    Notes:
  • Meta image files can often be authored at very high resolutions (sometimes in excess of 10,000 units for both the width and height) and this would lead to very large converted image sizes. To combat this it is possible to set the maximum total area of the rendered image as a value in megapixels (similar to the way that digital cameras have their resolutions quoted). If a meta image file's width x height is greater than the specified number of mega pixels then it is re-sized to be within this value. It is important to note that this "re-size" is actually a meta image file rendering transformation and not a "re-size" in the strictest sense (see the I2PDF_MetaImageScale_Int API below for this option).
  • Here is a list of common mega pixel sizes and an example of an image size that just fits within this limit:
  • 13 = 1300 x 1000
    22 = 1800 x 1200
    31 = 2000 x 1600
    43 = 2400 x 1800
    53 = 2700 x 2000
    61 = 2900 x 2200
    82 = 3400 x 2500
    100 = 3700 x 2800
  • The default setting is 22

  •   I2PDF_MetaImageScale
    Parameters: percentage - specifies the meta image (EMF or WMF) scaling factor and must be a value between 1.0 and 100.0 inclusive.
    Return Value: 0 - success
    1 - invalid percentage parameter
    Notes:
  • In some circumstances rendering a meta image file at a lower resolution by using a lower value for I2PDF_MetaImageMaxMP can result in images whose lines and text look "jagged". In these cases you could try using a higher resolution I2PDF_MetaImageMaxMP and then re-sizing (or scaling) the resultant image with this command. This will have the effect of smoothing (or anti-aliasing) these "jagged" items.
  • The default setting is 100.0 - ie no scaling

  •   I2PDF_MetaImageScale_Int
    Parameters: percentage - specifies the meta image (EMF or WMF) scaling factor and must be a value between 1 and 100 inclusive.
    Return Value: 0 - success
    1 - invalid percentage parameter
    Notes:
  • In some circumstances rendering a meta image file at a lower resolution by using a lower value for I2PDF_MetaImageMaxMP_Int can result in images whose lines and text look "jagged". In these cases you could try using a higher resolution I2PDF_MetaImageMaxMP_Int and then re-sizing (or scaling) the resultant image with this command. This will have the effect of smoothing (or anti-aliasing) these "jagged" items.
  • The default setting is 100.0 - ie no scaling

  •   I2PDF_MetaStampImageMaxMP
    Parameters: max megapixel size - specifies the meta image (EMF or WMF) maximum rendering size for an image stamp and must be a value between 0.1 and 20.0 inclusive.
    Return Value: 0 - success
    1 - invalid max megapixel size parameter
    Notes:
  • Meta image files can often be authored at very high resolutions (sometimes in excess of 10,000 units for both the width and height) and this would lead to very large converted image sizes. To combat this it is possible to set the maximum total area of the rendered image as a value in megapixels (similar to the way that digital cameras have their resolutions quoted). If a meta image file's width x height is greater than the specified number of mega pixels then it is re-sized to be within this value. It is important to note that this "re-size" is actually a meta image file rendering transformation and not a "re-size" in the strictest sense (see the I2PDF_MetaStampImageScale API below for this option).
  • Here is a list of common mega pixel sizes and an example of an image size that just fits within this limit:
  • 1.3 = 1300 x 1000
    2.2 = 1800 x 1200
    3.1 = 2000 x 1600
    4.3 = 2400 x 1800
    5.3 = 2700 x 2000
    6.1 = 2900 x 2200
    8.2 = 3400 x 2500
    10.0 = 3700 x 2800
  • The default setting is 1.0

  •   I2PDF_MetaStampImageMaxMP_Int
    Parameters: max megapixel size - specifies the meta image (EMF or WMF) maximum rendering size for an image stamp and must be a value between 1 and 200 inclusive (this is divided by 10 internally to give a value between 0.1 and 20.0).
    Return Value: 0 - success
    1 - invalid max megapixel size parameter
    Notes:
  • Meta image files can often be authored at very high resolutions (sometimes in excess of 10,000 units for both the width and height) and this would lead to very large converted image sizes. To combat this it is possible to set the maximum total area of the rendered image as a value in megapixels (similar to the way that digital cameras have their resolutions quoted). If a meta image file's width x height is greater than the specified number of mega pixels then it is re-sized to be within this value. It is important to note that this "re-size" is actually a meta image file rendering transformation and not a "re-size" in the strictest sense (see the I2PDF_MetaStampImageScale_Int API below for this option).
  • Here is a list of common mega pixel sizes and an example of an image size that just fits within this limit:
  • 13 = 1300 x 1000
    22 = 1800 x 1200
    31 = 2000 x 1600
    43 = 2400 x 1800
    53 = 2700 x 2000
    61 = 2900 x 2200
    82 = 3400 x 2500
    100 = 3700 x 2800
  • The default setting is 10

  •   I2PDF_MetaStampImageScale
    Parameters: percentage - specifies the meta image (EMF or WMF) scaling factor for an image stamp and must be a value between 1.0 and 100.0 inclusive.
    Return Value: 0 - success
    1 - invalid percentage parameter
    Notes:
  • In some circumstances rendering a meta image file at a lower resolution by using a lower value for I2PDF_MetaStampImageMaxMP can result in images whose lines and text look "jagged". In these cases you could try using a higher resolution I2PDF_MetaStampImageMaxMP and then re-sizing (or scaling) the resultant image with this command. This will have the effect of smoothing (or anti-aliasing) these "jagged" items.
  • The default setting is 33.3 - ie scaled to one third of it's rendered size.

  •   I2PDF_MetaStampImageScale_Int
    Parameters: percentage - specifies the meta image (EMF or WMF) scaling factor for an image stamp and must be a value between 1 and 100 inclusive.
    Return Value: 0 - success
    1 - invalid percentage parameter
    Notes:
  • In some circumstances rendering a meta image file at a lower resolution by using a lower value for I2PDF_MetaStampImageMaxMP_Int can result in images whose lines and text look "jagged". In these cases you could try using a higher resolution I2PDF_MetaStampImageMaxMP_Int and then re-sizing (or scaling) the resultant image with this command. This will have the effect of smoothing (or anti-aliasing) these "jagged" items.
  • The default setting is 33 - ie scaled to one third of it's rendered size.

  •   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_MetaVerticalRenderScale
    Parameters: scale - specifies the meta image (EMF or WMF) vertical scaling factor during rendering and must be a value between 0.01 and 10.0 inclusive.
    Return Value: 0 - success
    1 - invalid scale parameter
    Notes:
  • In some circumstances rendering a meta image file may exhibit stretched text, to combat this you can set the vertical scaling to a value of less than 1.0 - try 0.5 to start with.
  • The default setting is 1.0 - ie no scaling

  •   I2PDF_MetaVerticalRenderScale_Int
    I2PDF_MetaVertRenderScale_Int
    Parameters: scale - specifies the meta image (EMF or WMF) vertical scaling factor during rendering and must be a value between 1 and 1000 inclusive.
    Return Value: 0 - success
    1 - invalid scale parameter
    Notes:
  • In some circumstances rendering a meta image file may exhibit stretched text, to combat this you can set the vertical scaling to a value of less than 100 - try 50 to start with.
  • Note: The scale value used in this API is divided by 100 internally to product a value between 0.01 and 10.0 inclusive as used in the above API.
  • The default setting is 100 - ie no scaling

  •   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_MetaBitmapForcedFontQuality
    I2PDF_MetaBitmapForcedFontQ
    Parameters: quality - must be one of the following:
  • DRAFT (1)
  • PROOF (2)
  • NONANTIALIASED (3)
  • ANTIALIASED (4)
  • CLEARTYPE (5)
  • Return Value: 0 - success
    1 - invalid quality
    Notes:
  • This API can only be used if the I2PDF_MetaToNativePDF API has NOT been used as it controls the font quality when rendering the meta image file into a bitmap.
  • There are instances where the font records stored in a meta image file may specify either a default setting which is dependent on the PC being used or a setting that is not desired. This API allows the font quality to be set to a known value.
  • Depending on your requirements you may want to use NonAntiAliased (when you want to ensure that the text pixels are either on or off only and not an interpolated color), AntiAliased (to make the text look smoother without adding any non-font color) or ClearType (which creates better looking text but does add colored pixels in - note that this may not always be available on a PC - it depends on which version of Windows is being used and how it may have been configured).