Tutorial #07: Images

In this tutorial, images are drawn using Graph::PlaneGeometry nodes with a two-dimensional texture applied. It has to be considered that the width and height of the texture have to be a number of the range 2^n (power of 2). Valid values are e.g. 1, 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024, 2048 etc.

Version 1: Flat Texture

For our tutorial we create an image named gfx_smiley.png and save it in the sub-folder gfx . The image is specified in the file package.xml :

    <Resource id="gfx_smiley" fileName="gfx/gfx_smiley.png"/>

In order to render the image, we need a suitable material with an activated texture unit. This material is created in the file graph_materials.xml. By using textureUnit0Enabled, the texture unit 0 is activated and blendMode="ALPHA" allows transparent sections to be drawn.

<?xml version="1.0"?>
<Graph>
    <Namespace id="material" activeAndVisible="no">
        
        <FixedProgram
            id="prg_color_texture"
            textureUnit0Enabled="yes"
        />
        
        <Material
            id="mat_alpha_color_texture"
            programId="prg_color_texture"
            visibleFaces="FRONT_AND_BACK"
            blendMode="ALPHA"
            depthBufferMode="NONE"
        />

Additionally, we create a Graph::FlatTexture node, which instantiates the image resource as graphic node. The attribute pixelFormat defines the format of the image in memory. It is possible that the pixel format in memory is different than the one stored in the resource file.

With the attribute useMipMaps it is possible to enable automatic mip-map generation. This means that a mip-map pyramid is created when loading the image. Enabling this attribute results in a higher loading time and 50% higher memory consumption. Usually, mip-mapping is not necessary for 2D applications, therefore, we disable it for our example.

        <FlatTexture
            id="texture_smiley"
            imageResourceId="package_main:gfx_smiley"
            pixelFormat="R8_G8_B8_A8"
            useMipMaps="no"
        />
        
    </Namespace>
</Graph>

In the file graph_main.xml we create an instance of these objects and activate them with MaterialState and TextureState.

<?xml version="1.0" ?>

<Graph>
    
    <Instance graphResourceId="package_main:graph_mat"/>
    <Instance graphResourceId="package_main:graph_camera"/>
    
    <MaterialState materialId="material/mat_alpha_color_texture"/>
    
    <TextureState textureId="material/texture_smiley"/>
    
    <PlaneGeometry
        id="plane"
        scaleFactorX="128" scaleFactorY="128"
    />
    
</Graph>

As a result, we receive a textured PlaneGeometry object:

tut0107_v1.png
Images V1 output window

Version 2: Position and Resize

The texture is always adjusted to the object. Depending on size and aspect ratio, the texture is scaled and/or deformed (see screenshot below).

By using the attributes texCoordX1, texCoordX2, texCoordY1 and texCoordY2 a section of the texture can be selected (see screenshot below).

    <PlaneGeometry
        id="plane7"
        scaleFactorX="64" scaleFactorY="128"
        texCoordX1="0.0" texCoordX2="0.5" texCoordY1="0.0" texCoordY2="1.0"
        posX="150" posY="0"
    />
    
    <PlaneGeometry
        id="plane8"
        scaleFactorX="128" scaleFactorY="64"
        texCoordX1="0.0" texCoordX2="1.0" texCoordY1="0.0" texCoordY2="0.5"
        posX="-150" posY="0"
    />
tut0107_v2.png
Images V2 output window

If the pixels of the texture graphic are exactly in between the pixel of the display surface after positioning the geometry object, the image appears blurry (see lowermost images in the screenshot above).

In order to avoid blurring, graphics always have to be placed on a whole-numbered position with an even-numbered pixel length. Graphics with an odd-numbered pixel length have to be placed in between two whole-numbered positions.

tut0107_pixel_interpolation.png
Pixel interpolation

Version 3: Colored Texture

If coloringEnabled and textureUnit0Enabled are activated, the color is calculated by multiplying these two color parameters. This can e.g. be used for fade-in/fade-out effects (alpha channel) or to color textures.

        <FixedProgram
            id="prg_color_texture"
            textureUnit0Enabled="yes"
            coloringEnabled="yes"
        />

For a better illustration, we create various material nodes and draw two overlapping PlaneGeometry objects with each node. The parameters for camera, light, texture and color are identical for all objects. The order is analogous to the reading flow from left to right and from top to bottom.

        <FixedProgram
            id="prg_white"
        />
        <Material
            id="mat_white"
            programId="prg_white"
        />
        
        <FixedProgram
            id="prg_color"
            coloringEnabled="yes"
        />
        <Material
            id="mat_color"
            programId="prg_color"
        />

The first two objects are drawn with the materials mat_white and mat_color. Although a texture parameter has been set, it is not drawn as textureUnit0Enabled is deactivated.

        <FixedProgram
            id="prg_texture"
            textureUnit0Enabled="yes"
        />
        <Material
            id="mat_texture"
            programId="prg_texture"
            visibleFaces="FRONT_AND_BACK"
            blendMode="NONE"
            depthBufferMode="NONE"
        />
        <Material
            id="mat_alpha_texture"
            programId="prg_texture"
            visibleFaces="FRONT_AND_BACK"
            blendMode="ALPHA"
            depthBufferMode="NONE"
        />
        
        <FixedProgram
            id="prg_color_texture"
            textureUnit0Enabled="yes"
            coloringEnabled="yes"
        />
        <Material
            id="mat_color_texture"
            programId="prg_color_texture"
            visibleFaces="FRONT_AND_BACK"
            blendMode="NONE"
            depthBufferMode="NONE"
        />
        <Material
            id="mat_alpha_color_texture"
            programId="prg_color_texture"
            visibleFaces="FRONT_AND_BACK"
            blendMode="ALPHA"
            depthBufferMode="NONE"
        />

For the next four objects the texture unit 0 has been activated. The materials vary in their values for the attributes coloringEnabled and blendMode. Only if the blendMode is set to "ALPHA", the alpha channel (transparency) is considered while drawing. The color parameter has an alpha value of 0.5, which is why the fourth object has a transparency of 50%.

        <FixedProgram
            id="prg_texture_light"
            textureUnit0Enabled="yes"
            coloringEnabled="no"
            lightingEnabled="yes"
        />
        <Material
            id="mat_texture_light"
            programId="prg_texture_light"
            visibleFaces="FRONT_AND_BACK"
            blendMode="ALPHA"
            depthBufferMode="NONE"
        />
        
        <FixedProgram
            id="prg_color_texture_light"
            textureUnit0Enabled="yes"
            coloringEnabled="yes"
            lightingEnabled="yes"
        />
        <Material
            id="mat_color_light"
            programId="prg_color_texture_light"
            visibleFaces="FRONT_AND_BACK"
            blendMode="NONE"
            depthBufferMode="NONE"
        />
        <Material
            id="mat_alpha_color_texture_light"
            programId="prg_color_texture_light"
            visibleFaces="FRONT_AND_BACK"
            blendMode="ALPHA"
            depthBufferMode="NONE"
        />

The last three objects have their attribute lightingEnabled set to "yes". Therefore, a simple lighting effect can be achieved with a suitable light source.

Note
It is also necessary to set the attribute hasNormal to "yes" for the illuminated PlaneGeometry objects. The calculation of the ligth intensity requires knowledge of the normal vectors for the respective geometry objects. Setting the hasNormal attribute causes the calculation of the normal vector for the corresponding PlaneGeometry object.
  <MaterialState materialId="material/mat_texture_light"/>
  <PlaneGeometry id="plane6"
    hasNormal="yes"
    scaleFactorX="128" scaleFactorY="128"
    posX="-150" posY="-150"
  />
  <PlaneGeometry id="plane6a"
    hasNormal="yes"
    scaleFactorX="128" scaleFactorY="128"
    posX="-145" posY="-145" depthOrder="1"
  />
tut0107_v3.png
Images V3 output window


Copyright © 2011-2017 Spraylight GmbH.