= !MapGuide RFC 38 - GETDYNAMICMAPOVERLAYIMAGE Enhancements for Selection = This page contains an 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||Oct 2 15:40:00 2007 || ||Last Modified||Jason Birch [[Timestamp]]|| ||Author||Trevor Wekel|| ||RFC Status||adopted|| ||Implementation Status||implemented|| ||Proposed Milestone||2.0|| ||Assigned PSC guide(s)|||| ||'''Voting History'''||Oct 31, 2007|| ||+1||Bob, Paul, Tom, Bruce, Andy, Jason|| ||+0|| || ||-0|| || ||-1|| || == Overview == Enhance the GETDYNAMICMAPOVERLAYIMAGE HTTP API to allow the selection and overlay images to be rendered as separate images. == Motivation == Currently, !MapGuide renders the selection and the overlay image as a single image. This requires all untiled layers to be redrawn whenever the selection is changed. This is an inefficient use of server-side rendering resources and it reduces multi-user performance for untiled maps. == Proposed Solution == Add the parameter BEHAVIOR to the existing GETDYNAMICMAPOVERLAYIMAGE. Increase the VERSION to 2.0.0 and deprecate the existing KEEPSELECTION parameter for the new version of the API. BEHAVIOR is a bitmask with the following values: {{{ RenderSelection = 1 // Renders the selected feature(s) RenderLayers = 2 // Renders the features on the map KeepSelection = 4 // Renders the selected feature(s) even if they are outside the current scale }}} Examples: * !RenderSelection | !RenderLayers will render selection and layers within the current scale * !RenderSelection | !KeepSelection will render only the selection regardless of scale Add a SELECTIONCOLOR parameter to the existing GETDYNAMICMAPOVERLAYIMAGE. The color may be specified as an integer or hex string and the encoding is specified as 8 bit RGBA values. Include support for "PNG8" in the FORMAT parameter of GETDYNAMICMAPOVERLAYIMAGE. For the Web Extensions API add an additional signature for !MgRenderingService.!RenderDynamicMapOverlay that includes an !MgRenderingOptions class: {{{ MgByteReader* RenderDynamicOverlay(MgMap* map, MgSelection* selection, MgRenderingOptions* options); }}} !MgRenderingOptions will contain information on the image format, the behavior, and the selection color {{{ class MgRenderingOptions { MgRenderingOptions(CREFSTRING format, INT32 behavior, MgColor* selectionColor); STRING GetImageFormat(); INT32 GetBehavior(); MgColor* GetSelectionColor(); } }}} Update the existing !WebLayout based ajax viewer to use the new API while maintaining the existing functionality. A new "selection" layer will not be added to the !WebLayout based viewer. === Addendum === A new selection overlay layer will be added to the AJAX viewer in release 2.1. The flexible viewer (Fusion) should also be updated to take advantage of this capability. == Implications == Since this is a new version of the HTTP request and a new signature for !RenderDynamicMapOverlay, compatibility with existing clients/scripts is maintained. The behavior parameter encapsulates the current "keepSelection" functionality so the existing !RenderDynamicOverlay methods could be deprecated in a future release. Features and their labels are returned in the !RenderLayers image. The selection image is place on top of this image. Therefore, labels will not overpost the selection as they do currently. We will rely on gd to perform the colorspace transformation for PNG8. Due to a limitation in gd, selection color transparency color will not be maintained. This means a PNG8 selection image will completely block out the features and labels underneath it. == Test Plan == Ensure that existing clients continue to function as expected. Verify that the new HTTP API renders only the selection or layers, or both depending on the behavior setting. == Funding/Resources == Autodesk will provide resources to implement the enhanced HTTP request. Time permitting, DM Solutions will update the new "Fusion" based viewer to include a new "selection" layer.