How can I change my map’s background to use an image?

Yes, you may add/change the background image of your map by configuring the vg_config.xml file within the map bundle.

The elements which you will need to know about within the vg_config.xml file are:

<texture>

For defining the background image to be used.

SYNTAX:

<texture
    id="string"
    resource="image name" >
</texture>

ATTRIBUTES:
id
A unique id which identifies that texture resource.

resource
The image to be loaded as a texture by the engine.  The resource must meet the following constraints:

• be a PNG
• have a pixel width and height that are equal
• have a pixel width and height that are a multiple of the power of two
• the image must be located in the map bundle’s “images” directory.

<background>

For defining how the background should appear behind the map and within the map surface view.

SYNTAX:

<background 
    resource="texture id" 
    scaleMode="string"
    widthInPixel="integer"
    heightInPixel="integer"
    color1="string" 
    color2="string" > 
</background>

ATTRIBUTES:
resource
A texture id which has been defined within the <texture> element.

scaleMode
The scaleMode determines how the image will be scaled. The options are:

• “eRepeat” – the image will be scaled (see widthInPixel and heightInPixel) and will be repeated  in order to fill the map surface
• “eNoScale” – the image will stretch to fit the map surface view, but no scaling will take place (i.e. it’s width/height ratio will be respected)
• “eExactFit” – the image will stretch and scale to fit within the map surface view.

widthInPixel and heightInPixel
Only valid if the scaleMode is set to “eRepeat”. Represents the pixel width and height dimensions to use for the repeating image.

color1 and color2
Where color1 represents the background color at the top of the map surface view and color2 represents the background color at the bottom of the map surface view.  The background color will only come into play if the image resource contains alpha transparency.
The color codes are RGBA values in hex code. For a reference to the possible values, please see this page.

For Example

You might have a configuration file like the excerpt below:

<!-- vg_config.xml -->    
<vg_config version="2">
<resources>
    <!-- ... -->
    <textures>
        <texture id="background_id" resource="my_background_file_name.png"/>
        <!-- ... -->
    </textures>
    <!-- ... -->
    <datasets>
        <dataset ...>
            <background resource="background_id" scaleMode="eExactFit" color1="0xffffffff" color2="0xffffffff"/>
            <!-- ... -->
        </dataset>
    </datasets>
    <!-- ... -->
</vg_config>