= !MapGuide RFC 148 - Support user-defined selection color in RenderMap =

This page contains a change request (RFC) for the !MapGuide Open Source project.
More !MapGuide RFCs can be found on the [wiki:MapGuideRfcs RFCs] page.

== Status ==

||RFC Template Version||(1.0)||
||Submission Date||20 Oct 2014||
||Last Modified||1 Nov 2014||
||Author||Jackie Ng||
||RFC Status||adopted||
||Implementation Status||implemented||
||Proposed Milestone||3.0||
||Assigned PSC guide(s)||(when determined)||
||'''Voting History'''||(vote date)||
||+1||Jackie,Gordon||
||+0||||
||-0||||
||-1||||
||no vote||Trevor,Kevin,Crispin,Haris||

== Overview ==

This RFC proposes to extend the RenderMap API to support user-defined selection colors

== Motivation ==

Currently, the RenderMap API does not offer the ability to pass in a custom selection color. As a result, any selections rendered via the RenderMap API will always be blue, which may not be suitable for particular maps.

== Proposed Solution ==

Add 2 new overloads of RenderMap that accepts a selection color to MgRenderingService. 

The first overload is based on the existing overload with the most parameters.

The other overload is to support invocation from the mapagent.

{{{
class MgRenderingService
{
PUBLISHED_API:
...
    /////////////////////////////////////////////////////////////////
    /// \brief
    /// Renders the specified MgMap to the requested image format.
    ///
    /// \param map
    /// Input
    /// map object containing current state of map.
    /// \param selection
    /// Input
    /// map feature selection. Specifies the selected features on the map
    /// \param center
    /// Input
    /// map center point. Specifies the center point for the map
    /// \param scale
    /// Input
    /// map scale. Specifies the scale for the map
    /// \param width
    /// Input
    /// image width. Specifies the image width in pixels
    /// \param height
    /// Input
    /// image height. Specifies the image height in pixels
    /// \param backgroundColor
    /// Input
    /// background color. Specifies the map background color
    /// \param format
    /// Input
    /// image format. Defines the format of the resulting image
    /// \param bKeepSelection
    /// Input
    /// true if you want to keep the selection
    /// \param selectionColor
    /// Input
    /// The color to use for rendered selections
    ///
    /// \return
    /// A byte reader containing the rendered image
    ///
    virtual MgByteReader* RenderMap(
        MgMap* map,
        MgSelection* selection,
        MgCoordinate* center,
        double scale,
        INT32 width,
        INT32 height,
        MgColor* backgroundColor,
        CREFSTRING format,
        bool bKeepSelection,
        MgColor* selectionColor) = 0;

    /////////////////////////////////////////////////////////////////
    /// \brief
    /// Renders the specified MgMap to the requested image format.
    ///
    /// \param map
    /// Input
    /// map object containing current state of map.
    /// \param selection
    /// Input
    /// map feature selection. Specifies the selected features on the map
    /// \param format
    /// Input
    /// image format. Defines the format of the resulting image
    /// \param bKeepSelection
    /// Input
    /// true if you want to keep the selection
    /// \param bClip
    /// Input
    /// true if you want to clip feature geometry
    /// \param selectionColor
    /// Input
    /// The color to use for rendered selections
    ///
    /// \return
    /// A byte reader containing the rendered image
    ///
    virtual MgByteReader* RenderMap(
        MgMap* map,
        MgSelection* selection,
        CREFSTRING format,
        bool bKeepSelection,
        bool bClip,
        MgColor* selectionColor) = 0;
};
}}}

In the mapagent, we'll introduce a version 3.0.0 GETMAPIMAGE that supports a user-defined selection color.

|| '''Name''' || '''Value'''  || '''Required''' || '''Description''' ||
|| OPERATION || GETMAPIMAGE || Yes || Operation to execute ||
|| VERSION || 3.0.0 || Yes || Operation version ||
|| CLIENTAGENT || text || Optional || Descriptive text for client ||
|| SESSION || session identifier || Optional || !MapGuide session identifier containing map to display.[[BR]]SESSION or USERNAME and PASSWORD must be specified. ||
|| USERNAME || text || Optional || !MapGuide user id.[[BR]]SESSION or USERNAME and PASSWORD must be specified.|| 
|| PASSWORD || text || Optional || Password for !MapGuide user.[[BR]]SESSION or USERNAME and PASSWORD must be specified. || 
|| MAPNAME || text || Optional || Name of the map to display.[[BR]]This corresponds to the !GetName() value for the resource identifier.[[BR]]MAPNAME or MAPDEFINITION must be specified. ||
|| MAPDEFINITION || text || Optional || Resource identifier for the map definition.[[BR]]MAPNAME or MAPDEFINITION must be specified. ||
|| FORMAT || JPG/PNG/PNG8 || Yes || Image format for rendered image ||
|| KEEPSELECTION || 0/1 || Optional || If true, render selected feature(s) even if they are outside the current scale. ||
|| SETVIEWCENTERX || double || Optional || Set X coordinate for center of map. ||
|| SETVIEWCENTERY || double || Optional || Set Y coordinate for center of map. ||
|| SETVIEWSCALE || double || Optional || Set scale for map. ||
|| SETDISPLAYDPI || integer || Optional || Set DPI for map. ||
|| SETDISPLAYWIDTH || integer || Optional || Set width of image in pixels. ||
|| SETDISPLAYHEIGHT || integer || Optional || Set height of image in pixels. ||
|| SHOWLAYERS || text || Optional || List of layers to display. ||
|| HIDELAYERS || text || Optional || List of layers to hide. ||
|| SHOWGROUPS || text || Optional || List of groups to display. ||
|| HIDEGROUPS || text || Optional || List of groups to hide. ||
|| CLIP || 0/1 || Optional || If true, additional clipping will be performed on image. ||
|| SELECTIONCOLOR || RGBA hex color || Optional || If specified, any selections rendered will use the specified color. Defaults to blue if not specified ||

== Implications ==

None. This is a new API.

== Test Plan ==

Add new rendering tests that pass in specific colors. Verify image output results.

== Funding / Resources ==

Community

== References ==

 * #2399