emfio/README.md

   1 # WMF/EMF/EMF+ Reader
   2
   3 ## Introduction
   4 The **emfio** module is used to read **WMF** (Windows Metafile), **EMF**
   5 (Enhanced Metafiles) and also **EMF+** (enhanced EMF) files [1], which are
   6 binary formats for vector images from Microsoft. These files can contain vector
   7 graphics, bitmap components and text.
   8
   9 This folder contains `emfio/source/reader` which is used for reading the
  10 WMF/EMF/EMF+ files, either directly, or inside a document. For embedding Windows
  11 Metafiles inside a document, one can use "Insert -> Picture -> From File" to put
  12 such a file into the document. It is possible to export the Windows Metafile
  13 by using right click and choose "save".
  14
  15 Most of the records of WMF/EMF formats come from the Windows Graphics Device.
  16 For Interface (GDI) API and EMF+ they come from the newer Windows GDI+.
  17
  18 More information about rendering Windows Metafiles can be found in the
  19 [Visual Class Library (VCL)](../vcl) and also in the
  20 [GDIMetaFile](../vcl/README.GDIMetaFile) documentation.
  21
  22 An example demo that renders a metafile using `vcl` be seen by invoking:
  23
  24     ./bin/run mtfdemo odk/examples/basic/forms_and_controls/burger.wmf
  25
  26 This opens the burger.wmf file from the ODK examples.
  27
  28 It is also possible to dump metaactions created as the intermediary format
  29 before rendering the metafile using:
  30
  31     ./bin/run mtfdemo -d odk/examples/basic/forms_and_controls/burger.wmf
  32
  33 If the command is successful, this message will be shown, and metadump.xml will
  34 be put in the current folder:
  35
  36 "Dumped metaactions as metadump.xml"
  37
  38 The demo code structure is described in [GDIMetaFile](../vcl/README.GDIMetaFile)
  39 documentation.
  40
  41 [1] [Windows Meta File](https://en.wikipedia.org/wiki/Windows\_Metafile),
  42 Wikipedia
  43
  44 ## EMF+ Specifics
  45 Handling EMF+ is to some extent different from handling WMF/EMF. More
  46 information can be found in the [VCL](../vcl)
  47 documentation.
  48
  49 ## How does it work?
  50 `emfio` module takes a byte array and turns it into a `drawinglayer` primitive container. The rendering is done via `drawinglayer` primitives. For more information, you should refer to [VCL](../vcl) documentation.
  51
  52 ## Limitations
  53 Not all the WMF/EMF/EMF+ records are supported by this module. Unsupported
  54 records are marked as "not implemented", and a warning message will printed
  55 if they are actually read within a file. You can file a bug report for
  56 implementing these records.
  57
  58 Currently, these records are not implemented (specified in
  59 `wmfreader.cxx`):
  60
  61 ```
  62 W_META_SETRELABS W_META_SETPOLYFILLMODE W_META_SETSTRETCHBLTMODE
  63 W_META_SETTEXTCHAREXTRA W_META_SETTEXTJUSTIFICATION W_META_FLOODFILL
  64 W_META_FILLREGION W_META_FRAMEREGION W_META_INVERTREGION
  65 W_META_PAINTREGION W_META_DRAWTEXT W_META_SETMAPPERFLAGS
  66 W_META_SETDIBTODEV W_META_REALIZEPALETTE W_META_ANIMATEPALETTE
  67 W_META_SETPALENTRIES W_META_RESIZEPALETTE W_META_EXTFLOODFILL
  68 W_META_RESETDC W_META_STARTDOC W_META_STARTPAGE W_META_ENDPAGE
  69 W_META_ABORTDOC W_META_ENDDOC
  70 ```
  71
  72 And these records are not implemented (specified in `emfreader.cxx`):
  73
  74 ```
  75 EMR_MASKBLT EMR_PLGBLT EMR_SETDIBITSTODEVICE EMR_FRAMERGN
  76 EMR_INVERTRGN EMR_FLATTENPATH EMR_WIDENPATH EMR_POLYDRAW
  77 EMR_SETARCDIRECTION EMR_SETPALETTEENTRIES EMR_RESIZEPALETTE
  78 EMR_EXTFLOODFILL EMR_ANGLEARC EMR_SETCOLORADJUSTMENT EMR_POLYDRAW16
  79 EMR_CREATECOLORSPACE EMR_SETCOLORSPACE EMR_DELETECOLORSPACE
  80 EMR_GLSRECORD EMR_GLSBOUNDEDRECORD EMR_PIXELFORMAT EMR_DRAWESCAPE
  81 EMR_EXTESCAPE EMR_STARTDOC EMR_SMALLTEXTOUT EMR_FORCEUFIMAPPING
  82 EMR_NAMEDESCAPE EMR_COLORCORRECTPALETTE EMR_SETICMPROFILEA
  83 EMR_SETICMPROFILEW EMR_TRANSPARENTBLT EMR_TRANSPARENTDIB
  84 EMR_GRADIENTFILL EMR_SETLINKEDUFIS EMR_SETMAPPERFLAGS EMR_SETICMMODE
  85 EMR_CREATEMONOBRUSH EMR_SETBRUSHORGEX EMR_SETMETARGN EMR_SETMITERLIMIT
  86 EMR_EXCLUDECLIPRECT EMR_REALIZEPALETTE EMR_SELECTPALETTE
  87 EMR_CREATEPALETTE EMR_ALPHADIBBLEND EMR_SETTEXTJUSTIFICATION
  88 ```
  89
  90 Due to the difference on the fonts available on various platforms, the outcome
  91 of text rendering can be different on Linux, Windows, macOS and elsewhere.
  92
  93 ## Known Bugs
  94 Known remaining bugs for this module is gathered here:
  95
  96 * [Bug 103859 \[META\] EMF/WMF (Enhanced/Windows Metafile) bugs and
  97 enhancements](https://bugs.documentfoundation.org/show\_bug.cgi?id=103859)
  98
  99 ## Dependencies
 100 The direct dependency for **emfio** is [**drawinglayer**](../drawinglayer). The
 101 complete list of dependencies including the indirect dependencies is as below:
 102 ```
 103 basegfx drawinglayer cppu cppuhelper sal comphelper tl salhelper vcl svt utl
 104 ```
 105
 106 ## Tools
 107 Several tools are available for inspecting WMF/EMF/EMF+ files, which are binary
 108 formats. Some of them are:
 109
 110 * [mso-dumper](https://git.libreoffice.org/mso-dumper/): Reads and dumps various
 111   binary formats from Microsoft including WMF/EMF/EMF+. The output is in a
 112   custom XML format. emf-dump.py and wmf-dump.py are usable.
 113 * [RE-lab (Formerly OLEToy)](https://github.com/renyxa/re-lab): Reads, dumps and
 114 modifies several binary formats from Microsoft including WMF/EMF/EMF+, and also
 115 other companies.
 116 * [EMF+ diagnostics reporting tool](https://github.com/chrissherlock/emfplus-decoder)
 117
 118 ## Related Software
 119 * [libemf](http://libemf.sourceforge.net/)
 120 * [libwmf](https://github.com/caolanm/libwmf)
 121
 122 ## References
 123 Documentation for WMF/EMF/EMF+ formats are available on Microsoft website:
 124
 125 * [\[MS-WMF\]: Windows Metafile Format](https://docs.microsoft.com/en-us/openspecs/windows\_protocols/ms-wmf/4813e7fd-52d0-4f42-965f-228c8b7488d2)
 126 * [\[MS-EMF\]: Enhanced Metafile Format](https://docs.microsoft.com/en-us/openspecs/windows\_protocols/ms-emf/91c257d7-c39d-4a36-9b1f-63e3f73d30ca)
 127 * [\[MS-EMFPLUS\]: Enhanced Metafile Format Plus Extensions](https://docs.microsoft.com/en-us/openspecs/windows\_protocols/ms-emfplus/5f92c789-64f2-46b5-9ed4-15a9bb0946c6)