= !MapGuide RFC 107 - Enhance Tile service to add a new API !GenerateTile  =

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||July 23, 2010||
||Last Modified||Ted Yang Aug 17, 2010||
||Author||Ted Yang||
||RFC Status||superceded ||
||Implementation Status||incomplete||
||Proposed Milestone||2.3||
||Assigned PSC guide(s)||||
||'''Voting History'''||||
||+1||||
||+0||||
||-0||||
||-1||||
||Abstained||||
 
== Overview ==

This RFC proposes to add a NEW !GenerateTile() API to the tile service. This new API will generate the tile on the server but not get the image from server.

== Motivation ==
MapGuide users want to allow easy pre-seeding of base map tiles, for example, to generate all the tiles of a map at one time, now they can call the API !GetTile:

Existing API:
{{{
    MgByteReader* GetTile(MgResourceIdentifier* mapDefinition,CREFSTRING baseMapLayerGroupName,INT32 tileColumn,INT32 tileRow,INT32 scaleIndex);
}}} 

There's one problem with this existing API, suppose the user run a tool(like Maestro !MgCooker) on the client PC to generate all the tiles of a map, the client will get the tile images from the server.
Actually the user just want to generate the tiles on the server to make the rendering/navigation of a map more smooth. But the transfer of the tile images will increase the cost to finish this job(usually thousands of tiles will be generate).
So this RFC want to add a NEW API !GenerateTile which generate the tile on the server and only return a bool value.


== Proposed Solution ==

Create a NEW !GenerateTile() API which return a bool value to indicate the tile generation is successful or not.

Proposed NEW API:
{{{
    /////////////////////////////////////////////////////////////////
    /// \brief
    /// Generate the specified base map tile for the given map. If a cached tile
    /// image exists return true, if not exists, the tile will be
    /// rendered and added to the cache, then return true.
    /// Any exception or error will return false.
    ///
    /// \param mapDefinition
    /// Input
    /// Resource identifier for the map definition
    /// \param baseMapLayerGroupName
    /// Input
    /// Specifies the name of the baseMapLayerGroup for which to render the tile.
    /// \param tileColumn
    /// Input
    /// Specifies the column index of the tile to return.
    /// \param tileRow
    /// Input
    /// Specifies the row index of the tile to return.
    /// \param scaleIndex
    /// Input
    /// Scale index to render.  Most detailed scale is index 0.
    ///
    /// \return
    /// A bool value to indicate the tile generation is successful or not.
    ///
    virtual bool GenerateTile(
        MgResourceIdentifier* mapDefinition,
        CREFSTRING baseMapLayerGroupName,
        INT32 tileColumn,
        INT32 tileRow,
        INT32 scaleIndex) = 0;
}}} 

== Implications ==

This change will NOT break existing API compatibility.

== Test Plan ==

 * !Build/Run on !Windows/Linux
 * New Unit test for !GenerateTile will be added

== !Funding/Resources ==

Supplied by Autodesk.