.. _flash:

*****************************************************************************
 Flash Output
*****************************************************************************

:Author:        Jeff McKenna
:Contact:       jmckenna at gatewaygeomatics.com
:Author:        Yewondwossen Assefa
:Contact:       assefa at dmsolutions.ca
:Last Updated: 2008/07/15

.. contents:: Table of Contents
    :depth: 2
    :backlinks: top


Introduction
============

Since MapServer 4.0, MapServer can output Flash files, in SWF format (or
"Shockwave Flash Format").  The following document outlines how to enable
Flash output in MapServer.

.. note::
   SWF is no longer supported in version 6.0.


Links to Flash-Related Information
----------------------------------

- `Open Source Flash Viewer`_
- `Flash maps demo`_

Installing MapServer with Flash Support
=======================================

To check that your mapserv executable includes Flash support, use the "-v"
command-line switch and look for "OUTPUT=SWF".

::

  $ ./mapserv -v
  MapServer version 5.2.0-rc1 OUTPUT=GIF OUTPUT=PNG OUTPUT=JPEG OUTPUT=WBMP
  OUTPUT=PDF OUTPUT=SWF OUTPUT=SVG SUPPORTS=PROJ SUPPORTS=AGG
  SUPPORTS=FREETYPE SUPPORTS=ICONV SUPPORTS=WMS_SERVER SUPPORTS=WMS_CLIENT
  SUPPORTS=WFS_SERVER SUPPORTS=WFS_CLIENT SUPPORTS=WCS_SERVER
  SUPPORTS=SOS_SERVER SUPPORTS=FASTCGI SUPPORTS=THREADS
  SUPPORTS=GEOS SUPPORTS=RGBA_PNG INPUT=JPEG INPUT=POSTGIS
  INPUT=ORACLESPATIAL INPUT=OGR INPUT=GDAL INPUT=SHAPEFILE


Using Pre-compiled Binaries
---------------------------

Windows users can use `MS4W`_, which supports SWF output.

Compiling MapServer with Flash Support
--------------------------------------

The library chosen to output SWF files is the `Ming library`_.  Ming is a C
library for generating SWF ("Flash") format movies, and it contains a set of wrappers
for using the library from C++ and popular scripting languages like PHP,
Python, and Ruby.


Building on Windows
*******************

- download the `Ming library`_ (the version currently supported is 0.2a)
- as of Ming 0.3 there was no makefile for Windows available in the distribution yet,
  but you can download a MS VC++ makefile (makefile.vc) from `here`_ (contains makefile
  and also libming.lib)
- copy makefile.vc under the src directory (ming-0.2/src)
- execute:

  ::

    nmake /f makefile.vc

- at this point you should have a libming.lib that will be linked with MapServer
- edit the nmake.opt in your MapServer directory and uncomment the MING=-DUSE_MING_FLASH
  flag, and point MING_DIR to your Ming directory.
- build MapServer as usual

Building on Unix
****************

Use the "--with-ming" configure flag to enable MING support on Unix. "--with-ming=dir"
will try to find the include files and library in the indicated directory.

::

  Note: compiling MapServer 4.4.2 with flash support (mingbeta version 0.3) requires
  the -DMING_VERSION_03 option otherwise the make fails. This option should be included
  in the configure.in after -DUSE_MING_FLASH as below:

     MING ENABLED= "-DUSE_MING_FLASH -DMING_VERSION_03"

How to Output SWF Files from MapServer
======================================

SWF output is specified by using the :ref:`OUTPUTFORMAT <outputformat>` object.
There are 2 possible output types:

1. A single movie containing the raster output for all the layers. To enable this,
   declare the following in the map file:

   ::

      OUTPUTFORMAT
        NAME swf
        MIMETYPE "application/x-shockwave-flash"
        DRIVER swf
        IMAGEMODE PC256
        FORMATOPTION "OUTPUT_MOVIE=SINGLE"
      END

2. A movie for every layer (vector movies for vector layers and raster
   movies for raster layers).  To enable this,
   declare the following in the map file:

   ::

      OUTPUTFORMAT
        NAME swf
        MIMETYPE "application/x-shockwave-flash"
        DRIVER swf
        IMAGEMODE PC256
        FORMATOPTION "OUTPUT_MOVIE=MULTIPLE"
      END


Other OutputFormat Options
--------------------------

- **FORMATOPTION "FULL_RESOLUTION=FALSE"**

  The FULL_RESOLUTION applies only for vector layers. If set to FALSE,
  filtering will be applied to the vector elements. It results in a smaller
  SWF file. The default value is TRUE.

- **FORMATOPTION "LOAD_AUTOMATICALLY=OFF"**

  Setting this option to OFF will not load the SWF files for each layer.
  The default value is ON.

Composition of the Resulting SWF Files
--------------------------------------

Several SWF Files will be produced from a single map file: there will be one SWF
file for each layer defined in the map file and one 'main' SWF file containing
critical information on the map file and the layers produced.

- The 'main' SWF File will contain Action Script (AS) code that gives critical
  information on the map file and the SWF layers produced. Basically there will
  be an object called mapObj containing the height, width, extent, scale, number
  of layers, etc. Here is an example (in AS) of the contents of this main movie:

  ::

    mapObj = new Object ();
    mapObj.name = "DEMO_SWF";
    mapObj.width = 400;
    mapObj.height = 300;
    mapObj.extent = "-2594561.353333,3467361.353333,3467361.353333,3840000.000000"; ;
    mapObj.numlayers = 4;
    mapObj.layers = new Array ();
    function LayerObj (name, type, fullname, relativename) {
    this.name = name;
    this.type = type;
    this.fullname = fullname;
    this.relativename = relativename;
    }
    mapObj.layers[0] = new LayerObj ("park", "2", "c:/tmp/ms_tmp/102389536132841_layer_0.swf", "102389536132841_layer_0.swf");
    mapObj.layers[1] = new LayerObj ("popplace", "4", "c:/tmp/ms_tmp/102389536132841_layer_1.swf", "102389536132841_layer_1.swf");
    mapObj.layers[2] = new LayerObj ("rail", "1", "c:/tmp/ms_tmp/102389536132841_layer_2.swf", "102389536132841_layer_2.swf");
    mapObj.layers[3] = new LayerObj ("road", "1", "c:/tmp/ms_tmp/102389536132841_layer_3.swf", "102389536132841_layer_3.swf");

  This example is produced based on a mapfile with two layers defined in it.
  We create a layer class object containing useful information on a layer. The parameters are:

  - Name : the name found in the map file
  - Type : the type of layer ( 0 = Point Layer; 1=Line; 2=Polygon; 3=Raster; 4=Annotation; 6=Circle)
  - Fullname : Full name of the file with path included
  - Relative name : Relative Name

  For example you can use mapObj.layers[0].name to extract the name of the first layer.

  Note: All map parameters from MapServer are not exported at this time. We should
  come up with a list of information of what we want to output. Note that this information
  can be used in a Flash application to load the SWF file, to build a legend, to build a
  scale bar, etc.

- SWF Files for each layer

  Each layer defined in the mapfile will have an associated SWF file created. The names of
  these SWF files are based on the name of the main file with an addition of 'layer_X'
  at the end of the name (where X is the layer index).

  These SWF files will contain vector and raster data as well as some Action Script
  depending on the layer and some configurations in the map file. We will see these
  configurations in detail in the following section.

Exporting Attributes
--------------------

Exporting attributes works on a layer basis (it is only available for Vector Layers).
To be able to export attributes to the SWF files, you have to define a metadata item called
SWFDUMPATTRIBUTES in the layer section of the mapfile. Here is an example :

::

  ...
  LAYER
  NAME park
  METADATA
    "DESCRIPTION""Parks"
    "RESULT_FIELDS" "NAME_E YEAR_EST AREA_KMSQ"
    "SWFDUMPATTRIBUTES" "NAME_E,AREA_KMSQ "
  END
  TYPE POLYGON
  STATUS ON
  DATA park
  ...

In the above example, the values for the attributes NAME_E and AREA_KMSQ will be exported
for each element in the layer.

The resulting SWF File will have the values of these attributes (written in Action Script).
Here is an example related to the above layer:

::

  nAttributes= 2;
  Attributes = new Array();
  Attributes[0] = "NAME_E";
  Attributes[1] = "AREA_KMSQ";
  Element = new Array ();
  Element[0] = new Array();
  Element[0][0] = "Ellesmere Island National Park Reserve";
  Element[0][1] = "1500";
  Element[1][0] = " Aulavik National park";
  Element[1][1] = "1500";

Events and Highlights
---------------------

Here is what is currently implemented concerning events (events here refer to mouse events
happening on an element. The available events are MOUSEUP, MOUSEDOWN, MOUSEOVER, MOUSEOUT):

- Events are only available for layers that have defined attributes exported (using
  SWFDUMPATTRIBUTES). This is like defining that a certain layer is queryable.
- When a mouse event happens on one of the elements, there is an Action Script call
  that is made: _root.ElementSelecetd(LayerId, ShapeId, Event) . The Flash application
  who wants to receive these events should define the function ElementSelected and
  use the information received to do actions like retrieving the attribute values from
  the specific SWF for the specified shape and display it.

In order to have highlighting, it has to be defined when the SWF is produced (basically
highlighting means that the shape is redrawn using a different color).

As of MapServer 5.0, highlighting is available on queryable layers by using the
QueryMap object in the map file to extract the color and do a highlight when on MOUSEOVER.
The current implementation will highlight all objects that are in a layer that uses
SWFDUMPATTRIBUTES, using the COLOR set in the QueryMap object in the mapfile.

Before MapServer 5.0, all objects that are in a layer that uses SWFDUMPATTRIBUTES are
highlighted using a red color.

Fonts
-----

Ming uses a special type of font called FDB files. It does not yet support Truetype fonts.
Please refer to ming documentation on how to `produce FDB files`_.

Outputting Raster SWF for Vector Layers
---------------------------------------

One mechanism would be to use the metadata for layer objects to define a raster output
for vector layers. We could use something like "SWFOUTPUT" "RASTER".  If this sounds desirable,
please file an enhancement `ticket`_ with this request, specifying the "Output-SWF" component.

What is Currently Supported and Not Supported
=============================================

1. Vector layers

   - Layer Point (case MS_LAYER_POINT) : *done*

     - msDrawMarkerSymbol
     - msDrawLabel

   - Layer line (case MS_LAYER_LINE) : *done*

     - msDrawLineSymbol
     - msDrawLabel

   - Layer circle ( case MS_LAYER_CIRCLE) : *not done* (should be done easily but missing data for testing)

     - omsCircleDrawLineSymbol

     - omsCircleDrawShadeSymbol

   - Layer annotation (case MS_LAYER_ANNOTATION): *done*

     - omsDrawMarkerSymbol
     - omsDrawLabel

   - Layer Polygon (MS_SHAPE_POLYGON): *done*

     - omsDrawShadeSymbol
     - omsDrawLineSymbol
     - omsDrawLabel

   - Vector Low Level functions

     - omsDrawMarkerSymbol

       - case(MS_SYMBOL_TRUETYPE) : *done*
       - case(MS_SYMBOL_PIXMAP) : *done*
       - case(MS_SYMBOL_ELLIPSE) : *done*
       - case(MS_SYMBOL_VECTOR) : *done*

     - omsDrawLineSymbol

       - case : simple line : *done*

   - drawing with the symbols : *not done*

     - omsDrawShadeSymbol

       - case : solid fill polygon : *done*
       - case : filled with symbols : cannot be implemented for now (tried to create
         a GD image to fill the shape but files created were huge)

     - omsCircleDrawLineSymbol : *not done*
     - omsCircleDrawShadeSymbol : *not done*
     - omsDrawLabel : *done*
     - omsDrawLabelCache : *done*
     - obillboard (shadow for texts) : *not done*

2. Raster Layer

   - msDrawRasterLayer: *done*

3. WMS Layer

   - msDrawWMSLayer: *done*

4. Surround components (Legend, scalebar) : *not supported*


.. #### rST Link Section ####

.. _`Open Source Flash Viewer`: http://aris.cseas.kyoto-u.ac.jp/fmv/
.. _`Flash maps demo`: http://mapserver.gis.umn.edu/docs/tutorial/demoflashmap/demoflashmaps
.. _`MS4W`: http://www.ms4w.com
.. _`Ming library`: http://www.libming.org/
.. _`here`: http://dl.maptools.org/dl/ming-0.2a.zip
.. _`hereold`: http://www2.dmsolutions.ca/mapserver/dl/ming-0.2a.zip
.. _`Produce FDB files`: http://www.opaque.net/wiki/index.php?MingFAQ
.. _`ticket`: https://github.com/mapserver/mapserver/issues/
