增强型 EMF/WMF 图元文件支持

概述

HotPDF 现在显著增强了 Enhanced Metafile（EMF）和 Windows Metafile（WMF）格式支持。新实现包含自动格式检测、多种定位选项、高级缩放控制，以及 PDF 文档中 vector graphics 的改进渲染质量

Key Enhancements

• 自动检测 EMF/WMF 格式并选择相应处理方式
• 多种定位选项（居中、左上角、自定义坐标）
• 增强的缩放和宽高比控制
• 直接 EMF 渲染以保留矢量图形
• 用于兼容性的位图转换选项
• 通过 THotPDF.EmfOptions 配置 fit 比例、EMF/WMF 渲染倍率、位图压缩、参考设备、stretch 模式和扩展 pen 线端/连接样式
• 针对大型图元文件的改进内存管理
• 更好地处理复杂矢量图形和文本

位置控制选项

增强型图元文件支持包含灵活的位置选项:

• mpCenter: 图元文件在页面上居中（默认行为）
• mpLeftTop: 图元文件显示在左上角 (X=0, Y=0)
• mpCustom: 图元文件显示在指定位置（需要 X、Y 参数）

使用示例

基础用法（默认居中显示）

// Delphi example - default centered display
procedure ShowMetafileDefault;
var
  PDF: THotPDF;
  MetaFile: TMetafile;
begin
  PDF := THotPDF.Create(nil);
  MetaFile := TMetafile.Create;
  try
    PDF.BeginDoc;
    PDF.AddPage;

    // Load metafile
    MetaFile.LoadFromFile('diagram.emf');

    // Display centered on page (default)
    PDF.CurrentPage.ShowMetafile(MetaFile);

    PDF.EndDoc;
  finally
    MetaFile.Free;
    PDF.Free;
  end;
end;
        

位置控制用法

// Delphi example - Advanced positioning
procedure ShowMetafileAdvanced;
var
  PDF: THotPDF;
  MetaFile: TMetafile;
begin
  PDF := THotPDF.Create(nil);
  MetaFile := TMetafile.Create;
  try
    PDF.BeginDoc;
    PDF.AddPage;

    MetaFile.LoadFromFile('chart.wmf');

    // Top-left corner display
    PDF.CurrentPage.ShowMetafile(MetaFile, mpLeftTop);

    // Custom position display
    PDF.CurrentPage.ShowMetafile(MetaFile, mpCustom, 100, 200);

    PDF.EndDoc;
  finally
    MetaFile.Free;
    PDF.Free;
  end;
end;
        

单次调用渲染选项

// Delphi example - Per-call options
procedure ShowMetafileWithOptions;
var
  PDF: THotPDF;
  MetaFile: TMetafile;
  Options: THPDFEmfOptions;
begin
  PDF := THotPDF.Create(nil);
  MetaFile := TMetafile.Create;
  Options := THPDFEmfOptions.Create;
  try
    Options.EmfBitmapScale := 1;
    Options.ColorImageCompression := icFlate;
    Options.UseScreenReferenceDC := False;
    Options.CanvasOver := True;
    Options.Redraw := False;
    Options.UseFrame := True;
    Options.ShowNullPen := True;
    Options.ShowNullBrush := True;

    PDF.BeginDoc;
    PDF.AddPage;
    MetaFile.LoadFromFile('diagram.emf');
    PDF.CurrentPage.ShowMetafile(MetaFile, mpCenter, 0, 0, Options);
    PDF.EndDoc;
  finally
    Options.Free;
    MetaFile.Free;
    PDF.Free;
  end;
end;
        

Enhanced Methods

增强型 EMF/WMF 支持引入了几个新方法:

THPDFPage.ShowMetafile 重载

• ShowMetafile(MetaFile: TMetafile) - 默认居中显示
• ShowMetafile(MetaFile: TMetafile; Position: THPDFMetafilePosition) - 位置控制
• ShowMetafile(MetaFile: TMetafile; Position: THPDFMetafilePosition; X, Y: Single) - 自定义定位
• ShowMetafile(MetaFile: TMetafile; Options: THPDFEmfOptions) - 每次调用独立的渲染选项
• ShowMetafile(MetaFile: TMetafile; Position: THPDFMetafilePosition; X, Y: Single; Options: THPDFEmfOptions) - 位置控制加每次调用独立的渲染选项
• ShowMetafileEx(MetaFile: TMetafile; Options: THPDFEmfOptions) - 直接页面 API，带单次绘制的 EMF/WMF 选项覆盖

增强处理方法

• EnhancedShowMetafile- 使用增强特性的高级处理
• ShowEnhancedMetafile(Page, MetaFile, Options) - 全局辅助函数，带每次调用独立的渲染选项
• ShowEnhancedMetafile(Page, MetaFile, Position, X, Y, Options) - 全局辅助函数，带位置控制与每次调用独立的渲染选项
• ShowEnhancedMetafile(Page, FileName, Options) - 文件名辅助函数，带每次调用独立的渲染选项
• ShowEnhancedMetafile(Page, FileName, Position, X, Y, Options) - 文件名辅助函数，带位置控制与每次调用独立的渲染选项
• RenderEmfDirect - 用于保留矢量的直接 EMF 渲染
• RenderEmfAsBitmap - 用于兼容性的位图转换
• RenderWmfAsBitmap - 带位置控制的 WMF 位图渲染

技术实现

增强 EMF/WMF 支持通过 HPDFEmf.pas 单元实现，该单元提供以下内容：

• THPDFEmfEnhanced: 用于 EMF 处理的核心增强类
• THPDFEmfPatcher:用于 EMF 转换和渲染的实用类
• THPDFMetafilePosition: 用于位置控制的枚举
• Enhanced EMF Record Processing: 支持高级 EMF 记录

THPDFPageHelper 与 C++ 边界

在 Delphi XE2 及更高版本上，上面列出的 THPDFPage.ShowMetafile 和 THPDFPage.EnhancedShowMetafile 重载由 THPDFPageHelper 注入——这是声明在 HPDFEmf 单元里的一个 class helper，只要把 HPDFEmf 加进 uses 子句，就能在任意 THPDFPage 实例上调用它们

class helper 是 Delphi 独有的语言特性，C++Builder 无法访问：C++ 调用方请改用 Enhanced Processing Methods 下列出的全局 ShowEnhancedMetafile(Page, MetaFile, ...) 辅助函数，与 ConvertTo 示例的做法完全一致

在 XE2 之前的 Delphi 版本上，同样的功能以普通兼容过程的形式暴露，页面作为第一个参数传入：THPDFPage_ShowMetafile(Page, MetaFile)、THPDFPage_ShowMetafile(Page, MetaFile, Position, X, Y)、THPDFPage_EnhancedShowMetafile(Page, MetaFile) 和 THPDFPage_EnhancedShowMetafile(Page, MetaFile, Position, X, Y)

增强开关

增强路径由 HPDFEmf 中的 EmfSupportEnabled: Boolean 变量守护，默认为 True；把它设为 False 后，所有图元文件显示都会回退到基础渲染路径

退出增强路径后，调用 EnableEnhancedEmfSupport 可以把它重新打开，示例程序正是在第一次调用 ShowMetafile 之前使用这个模式

Advanced Features

EMF Record Support

• EMR_BITBLT - Bitmap operations
• EMR_STRETCHDIBITS - Stretched bitmap operations
• EMR_ALPHABLEND - Alpha blending operations
• 增强型文本渲染
• 复杂路径操作

Rendering 选项

• Vector Preservation: 保持矢量图形质量
• Bitmap Fallback: 复杂图形的自动回退
• Scaling 选项: 自动和手动缩放控制
• Quality Control:可配置的渲染质量设置
• Canvas Layering: 设置EmfOptions（需要既有页面内容画在回放的 Canvas 图元文件内容之上时）
• 重绘控制：默认的临时重绘路径保持 THPDFEmfOptions.Redraw 启用；要直接解析原始图元文件则关闭它
• Frame 裁剪：导入的图元文件依赖 frame 边界时，设置 THPDFEmfOptions.UseFrame 把 EMF 输出裁剪到 header frame
• 阴影画刷图案：EMF/WMF 阴影画刷映射为 PDF tiling pattern，导入图形保留填充纹理
• 空对象诊断：空画笔与空画刷默认不可见；诊断需要这些路径或填充可见时，设置 THPDFEmfOptions.ShowNullPen 与 THPDFEmfOptions.ShowNullBrush（诊断需要这些路径或填充可见时）

性能优化

• 大型图元文件的内存高效处理
• 优化的 EMF 记录解析
• 重复元素的智能缓存
• 转换期间降低内存占用

兼容性和标准

• 支持 Windows EMF 1.0 和 Enhanced EMF
• Windows Metafile (WMF) 向后兼容
• 跨平台渲染一致性
• 符合 PDF 矢量图形标准

Troubleshooting

常见问题和解决方案:

• Large Metafiles: 对于非常大或复杂的图元文件使用位图渲染
• Text Rendering: 确保目标系统上有可用字体
• Complex Graphics: 为获得更好质量，可考虑直接 EMF 渲染
• Positioning Issues: 使用自定义定位实现精确放置

另请参阅

• THPDFPage.ShowMetafile Method
• JPEG2000 Support
• THotPDF.AddImage Method
• Vector Graphics Overview