Turn Radek's notes into README files.

Change-Id: I904142622ac37b394ddedf62bb7d9c099fc9cab4

avmedia/README

@@ -7,4 +7,19 @@ streaming has to be wrapped around it via temp files.
 Also provides (in source/framework/mediacontrol.cxx) an implementation
 of the graphical media playback control that appears in the toolbar /
 mediaobject bar when media is selected under the .uno:AVMediaToolBox
-item.
\ No newline at end of file
+item.
+
+== avmedia/gstreamer ==
+
+The avmedia component is implementation of manager service defined in
+offapi/com/sun/star/media/. Radek has added implementation based on
+gstreamer so that we can add audio and video files into impress
+presentation on Linux with gstreamer.
+
+The implementation is pretty straightforward, sometimes it has
+problems when gstreamer installation is incomplete.
+
+In the beginning the media files were not embedded, Thorsten added
+support for that later.
+
+FUTURE work: it might be worthwhile to revamp the avmedia UI

canvas/README

@@ -24,3 +24,23 @@ presentation framework with a fully independent UNO component, and it
 is based on the canvas. Some features used there are only available
 from canvas, like double-buffering, and hardware-accelerated
 alpha-blending (currently not on all platforms).
+
+== Cairo canvas ==
+
+cairo canvas is one of backends of canvas component. canvas is mostly
+used for slideshow rendering and also for emf+ rendering. we hoped it
+will even be used by drawing layer, but it didn't happen (yet?) for
+API look at offapi/com/sun/star/rendering/, the implementation is in
+canvas and cppcanvas modules.
+
+cairo canvas backend uses cairo library for rendering. main advantage
+is support of alpha transparency and in some cases accelerated
+rendering.
+
+the backend itself is quite old and stable, not many changes in that
+area lately, mostly changes for emf+ rendering, communication with
+vcl and bugfixes
+
+FUTURE work: look at cairo canvas and situation when it is used
+(mostly slideshow). TODO there still might be more cases when we
+can save some roundtrips when exchanging data with vcl.

cppcanvas/README

 Helper C++ classes for [[canvas]], plus a GDIMetaFile-to-XCanvas converter.
+
+== EMF+ ==
+
+For cppcanvas/source/mtfrenderer, see the README in vcl (the EMF+ part).

oox/README

@@ -2,3 +2,188 @@ Support for Office Open XML, the office XML-format designed by Microsoft.
 
 See also:
 [http://wiki.services.openoffice.org/wiki/OOX]
+
+== DrawingML Custom shapes and presets ==
+
+custom shapes are part of DrawingML and are different to binary ppt
+and VML in older formats, so we needed to add new code to work with
+these. the import happens in oox/source/drawingml, where they are
+imported as LO's enhanced custom shape's. see
+offapi/com/sun/star/drawing/CustomShape.idl and
+offapi/com/sun/star/drawing/EnhancedCustomShape*.idl
+
+the export is quite behind now, as it was done before we started work
+on fully supporting drawingml custom shapes. (see FUTURE WORK below)
+
+example of drawingml preset:
+
+         <a:prstGeom prst="star5">
+           <a:avLst/>
+         </a:prstGeom>
+
+example of drawingml custom shape (equal to star5 preset):
+
+   <avLst xmlns="http://schemas.openxmlformats.org/drawingml/2006/main">
+     <gd name="adj" fmla="val 19098" />
+     <gd name="hf" fmla="val 105146" />
+     <gd name="vf" fmla="val 110557" />
+   </avLst>
+   <gdLst xmlns="http://schemas.openxmlformats.org/drawingml/2006/main">
+     <gd name="a" fmla="pin 0 adj 50000" />
+     <gd name="swd2" fmla="*/ wd2 hf 100000" />
+     <gd name="shd2" fmla="*/ hd2 vf 100000" />
+     <gd name="svc" fmla="*/ vc  vf 100000" />
+     <gd name="dx1" fmla="cos swd2 1080000" />
+     <gd name="dx2" fmla="cos swd2 18360000" />
+     <gd name="dy1" fmla="sin shd2 1080000" />
+     <gd name="dy2" fmla="sin shd2 18360000" />
+     <gd name="x1" fmla="+- hc 0 dx1" />
+     <gd name="x2" fmla="+- hc 0 dx2" />
+     <gd name="x3" fmla="+- hc dx2 0" />
+     <gd name="x4" fmla="+- hc dx1 0" />
+     <gd name="y1" fmla="+- svc 0 dy1" />
+     <gd name="y2" fmla="+- svc 0 dy2" />
+     <gd name="iwd2" fmla="*/ swd2 a 50000" />
+     <gd name="ihd2" fmla="*/ shd2 a 50000" />
+     <gd name="sdx1" fmla="cos iwd2 20520000" />
+     <gd name="sdx2" fmla="cos iwd2 3240000" />
+     <gd name="sdy1" fmla="sin ihd2 3240000" />
+     <gd name="sdy2" fmla="sin ihd2 20520000" />
+     <gd name="sx1" fmla="+- hc 0 sdx1" />
+     <gd name="sx2" fmla="+- hc 0 sdx2" />
+     <gd name="sx3" fmla="+- hc sdx2 0" />
+     <gd name="sx4" fmla="+- hc sdx1 0" />
+     <gd name="sy1" fmla="+- svc 0 sdy1" />
+     <gd name="sy2" fmla="+- svc 0 sdy2" />
+     <gd name="sy3" fmla="+- svc ihd2 0" />
+     <gd name="yAdj" fmla="+- svc 0 ihd2" />
+   </gdLst>
+   <ahLst xmlns="http://schemas.openxmlformats.org/drawingml/2006/main">
+     <ahXY gdRefY="adj" minY="0" maxY="50000">
+       <pos x="hc" y="yAdj" />
+     </ahXY>
+   </ahLst>
+   <cxnLst xmlns="http://schemas.openxmlformats.org/drawingml/2006/main">
+     <cxn ang="3cd4">
+       <pos x="hc" y="t" />
+     </cxn>
+     <cxn ang="cd2">
+       <pos x="x1" y="y1" />
+     </cxn>
+     <cxn ang="cd4">
+       <pos x="x2" y="y2" />
+     </cxn>
+     <cxn ang="cd4">
+       <pos x="x3" y="y2" />
+     </cxn>
+     <cxn ang="0">
+       <pos x="x4" y="y1" />
+     </cxn>
+   </cxnLst>
+   <rect l="sx1" t="sy1" r="sx4" b="sy3" xmlns="http://schemas.openxmlformats.org/drawingml/2006/main" />
+   <pathLst xmlns="http://schemas.openxmlformats.org/drawingml/2006/main">
+     <path>
+       <moveTo>
+         <pt x="x1" y="y1" />
+       </moveTo>
+       <lnTo>
+         <pt x="sx2" y="sy1" />
+       </lnTo>
+       <lnTo>
+         <pt x="hc" y="t" />
+       </lnTo>
+       <lnTo>
+         <pt x="sx3" y="sy1" />
+       </lnTo>
+       <lnTo>
+         <pt x="x4" y="y1" />
+       </lnTo>
+       <lnTo>
+         <pt x="sx4" y="sy2" />
+       </lnTo>
+       <lnTo>
+         <pt x="x3" y="y2" />
+       </lnTo>
+       <lnTo>
+         <pt x="hc" y="sy3" />
+       </lnTo>
+       <lnTo>
+         <pt x="x2" y="y2" />
+       </lnTo>
+       <lnTo>
+         <pt x="sx1" y="sy2" />
+       </lnTo>
+       <close />
+     </path>
+   </pathLst>
+
+we needed to extend our custom shapes for missing features and so 5
+new segment commands were added. G command for arcto drawingml record
+and H I J K commands for darken, darkenless, lighten, lightenless
+records. the commands are save into ODF in special namespace drawooo,
+which is extension not yet in the standard. Thorsten suggested to put
+it in such a namespace and keep original (incomplete) geometry for
+backward compatibility, before we can extend the ODF. that's why you
+will see 2 of them in cases where some of the new commands was
+needed. Radek backported code for the new commands to 3-6
+and 4-0 branches.
+
+the drawingml also contains new presets (compared to binary/VML) and
+so we now have code with these presets - they are basicallly
+predefined custom shapes. we generate them using scripts in
+oox/source/drawingml/customshapes/ and the output are
+oox/source/drawingml/customshapepresets[123456].cxx source files
+containing the definition for the preset shapes. this mean that we
+import presets from OOXML files perfectly. one area to look at might
+be check how handles on the imported custom shapes (and presets)
+wotk.
+
+the source code generation happens in these steps:
+
+  * generate pptx files by running generatePresetsPPTXs.pl. it
+    generates files in pptx/ from cshape.pptx sample - replacing
+    slide1.xml in it and placing it in new file in pptx/ named after
+    the preset plus one cshape-all.pptx file all the presets
+
+  * build oox module with debug (ie. make -s debug=t dbglevel=2)
+
+  * import cshape-all.pptx into impress and redirect output to
+    custom-shapes.log
+
+  * generate cxx files by running generatePresetsCXX.pl - it uses
+    debug output from the custom-shapes.log file and prepares the C++
+    source code
+
+  * check generated source code files customshapepresets[123456].cxx
+    and move them to oox/source/drawingml/
+
+  * build oox with new source files and test
+
+while importing presets, we also set the name of the custom shape so
+that we can detect it on export as save it again as preset.
+
+the scripts in oox/source/drawingml/customshapes/ also generate pptx
+files for signle presets and also for all presets
+cshape-all.pptx. the cshape-all.pptx file is then loaded into impress
+build with debug enabled in oox and the command line output contains
+information, which are used by generatePresetsCXX.pl. redirect the
+output into custom-shapes.log in oox/source/drawingml/customshapes/
+and run the script. it creates the customshapepresets[123456].cxx
+source files with presets definitions. also the generated pptx files
+can be used when debugging bugs in custom shapes import/export. also
+the cshape-all.pptx can be used to test the round trips. there's small
+problem with these pptx as they cannot be imported into powerpoint,
+but that can be fixed quickly. when fixed, we can use it to
+test powerpoint odp export and see how complete it is regarding
+custom shapes. OpenXML SDK tools might help when fixing
+cshape-all.pptx
+http://www.microsoft.com/en-us/download/details.aspx?id=30425
+
+FUTURE WORK: because we have to make sure that all the roundtrips
+like PPTX --> ODP --> PPTX work correctly and doesn't loose data.
+the only problematic part is probably saving custom shapes (ie. not
+presets) to PPTX. that part of code predates work on custom shapes
+and is unable to export general custom shapes yet. it will need a bit
+of work as LO has more complex equations than DrawingML. other parts
+should work OK, PPTX --> ODP should work and don't loose any
+data. presets should already survive PPTX --> ODP --> PPTX roundtrip

sd/README

@@ -22,3 +22,22 @@ pptx. their locations are listed bellow:
    oox/source/drawingml and oox/source/*)
  * pptx export is in sd/source/filter/eppt (mostly in pptx-* source
    files) and shared part is in oox/source/export
+
+== PPTX export/import filters ==
+
+PPTX export filter is split into 2 parts. Impress related part is in
+sd/source/filter/eppt/pptx-* and the other part is in
+oox/source/export/ because it contains mostly code related to
+DrawingML, which is shared with writer and calc ooxml export.
+
+The export filter was written in 2009 IIRC and was not much extended
+feature-wise lately.
+
+FUTURE work: add custom shapes export (see below). enhance text
+output, we don't write text style for indentation levels now, need to
+export a:lvl1pPr, a:lvl2pPr, ... elements.
+
+PPTX import was written by Sun/Oracle and then extended in LibreOffice
+a lot during bug fixing. It is located in oox/source/ppt and
+oox/source/drawingml. The areas with most bugs (at least until today)
+were shape placeholders and text style inheritance.

slideshow/README

 The Impress slideshow engine
+
+== 3D transitions ==
+
+The 3D transitions are slideshow transition engine using OpenGL and
+are located in slideshow/source/engine/OGLTrans/. They were initially
+written by GSOC student Shane.M.Mathews. Radek has later polished the
+code a bit, added few new 3D transitions, added infrastructure for
+vertex and fragment shaders. Wrote few transitions with fragment shader
+too.

vcl/README

@@ -63,3 +63,68 @@ Note: references to "SV" in the code mean StarView, which was a
 portable C++ class library for GUIs, with very old roots, that was
 developed by StarDivision. Nowadays it is not used by anything except
 LibreOffice (and OpenOffice).
+
+== EMF+ ==
+
+emf+ is vector file format used by MSO and is successor of wmf and
+emf formats. see
+http://msdn.microsoft.com/en-us/library/cc230724.aspx for
+documentation. note that we didn't have this documentation from
+start, so part of the code predates to the time when we had guessed
+some parts and can be enhanced today. there also still many thing not
+complete
+
+emf+ is handled a bit differently compared to original emf/wmf files,
+because GDIMetafile is missing features we need (mostly related to
+transparency, argb colors, etc.)
+
+emf/wmf is translated to GDIMetafile in import filter
+vcl/source/filter/wmf and so special handling ends here
+
+emf+ is encapsulated into GDIMetafile inside comment records and
+parsed/rendered later, when it reaches cppcanvas. it is parsed and
+rendered in cppcanvas/source/mtfrenderer. also note that there are
+emf+-only and emf+-dual files. dual files contains both types of
+records (emf and emf+) for rendering the images. these can used also
+in applications which don't know emf+. in that case we must ignore
+emf records and use emf+ for rendering. for more details see
+documentation
+
+parsing:
+
+ wmf/emf filter --> GDI metafile with emf+ in commments --> cppcanvas metafile renderer
+
+lately the GDIMetafile rendering path changed which also influenced
+emf+ rendering. now many things happen in drawing layer, where
+GDIMetafile is translated into drawing layer primitives. for
+metafiles with emf+ we let the mtfrenderer render them into bitmap
+(with transparency) and use this bitmap in drawinlayer. cleaner
+solution for current state would be to extend the drawing layer for
+missing features and move parsing into drawing layer (might be quite
+a lot of work). intemediary enhancement would be to know better the
+needed size/resolution of the bitmap, before we render emf+ into
+bitmap in drawing layer. Thorsten is working on the same problem with
+svg rendering, so hopefully his approach could be extended for emf+ as
+well. the places in drawing layer where we use canvas mtfrenderer to
+render into bitmaps can be found when you grep for GetUseCanvas. also
+look at vcl/source/gdi/gdimetafile.cxx where you can look for
+UseCanvas again. moving the parsing into drawinglayer might also have
+nice side effect for emf+-dual metafiles. in case the emf+ records
+are broken, it would be easier to use the duplicit emf
+rendering. fortunatelly we didn't run into such a broken emf+ file
+yet. but there were already few cases where we first though that the
+problem might be because of broken emf+ part. so far it always turned
+out to be another problem.
+
+rendering:
+
+ before
+
+ vcl --> cppcanvas metafile renderer --> vcl
+
+ now
+
+ drawing layer --> vcl --> cppcanvas metafile renderer --> vcl --> drawing layer
+
+another interesting part is actual rendering into canvas bitmap and
+using that bitmap later in code using vcl API.