Resource Object Types

This page gives you an overview of different types of resource objects that can be imported to and used in the Murl Engine. The individual types are described as such, and different possible input file formats for each type are explained.

Resource objects must usually be grouped together to form logical resource packages in order to be used with the Murl Engine. The following sub-sections contain type-specific information on how to define and parameterize different resource objects, so it is assumed that you already have a basic understanding of how to create such a package. See the Cube V2 tutorial and the Resource Package XML Description pages for details.

The following list states the different resource object types described on this page. Click on a link to quickly jump to the respective section.

Graph Resources

With the scene graph being a central component of the Murl Engine, it is necessary to define the actual contents of that scene graph somewhere. Besides the possibility of creating from code, XML graph resource files provide an easy way to define the structure of a scene graph for application-specific purposes.

Graph resources are available in form of Resource::IGraph objects when accessed from code.

XML Graphs

XML graph resource files are recognized by their <Graph> root element. Within that element the actual scene graph nodes can be hierarchically defined by creating node elements with their type-specific tag and type-specific attributes.

The Murl Engine provides a number of different node classes that can be instantiated. The Murl::Graph Node Classes page in the API Reference provides a list of all available nodes, with Graph::Node as the base class for all other ones. The API Reference for these nodes contain a "XML Elements" section, which can be used to find out which tag and attributes to use. You can also visit the XML Graph Node Tags page for a compressed list of available classes and tags, and the XML Graph Node Attributes page for their attributes.

Here is an example of a simple scene graph XML file:

<?xml version="1.0" ?>

<Graph>
    <View id="view"/>
    <Camera viewId="view" fieldOfViewX="2">
        <FixedProgram id="prog"/>
        <Material programId="prog">
            <PlaneGeometry posZ="-1"/>
        </Material>
    </Camera>
</Graph>

See also the Cube V2 and other tutorials.

Note, that it is also possible to specify a graph node's namespace (excluding the top-level Murl namespace) for its tag, e.g. a Material node can also be specified as follows:

    <Graph::Material programId="prog">
        <PlaneGeometry posZ="-1"/>
    </Graph::Material>

As long as you only work with the predefined nodes that come with the Murl Engine core, it is not necessary to do so. However, when you create your own custom material class from your application using the same name (see the Creating Custom Graph Nodes page), it may become necessary to specify that node's namespace, e.g.:

    <MyApp::Material programId="prog"/>

In addition, there may be future add-on libraries for the Murl Engine that require you to do so.

When omitting the namespace scope for a node element's tag, the engine looks for the first occurrence of a node with the given name and creates an instance for that one. It is guaranteed that all nodes listed in the XML Graph Node Tags reference are registered first. This means that specifying a <Material> element will always create a Murl::Graph::Material node, even if you register your own MyApp::Material later on (unless you manually unregister the Murl::Graph::Material node class, which should only be done with care).

With XML graph files, it is also possible to define custom attributes that get evaluated when a (sub-)graph is instantiated from such a file as described on the Instances and References page.

Image Resources

When specified via a <Resource> element in a package.xml file, image resources share the following common attributes:

  • outputStreamFormat: This attribute accepts one of the available IEnums::VideoStreamFormat enumeration string values, which specify the actual image format, in which the image is stored in the package (currently only PNG and WEBP are supported). In other words, it is possible to e.g. convert a given PNG image to a WEBP image at load-time: 
    <Resource id="img1" fileName="test.png" outputStreamFormat="WEBP"/>
    Note, that when the binary .murlpkg package is created using the Resource Packer tool, this conversion is done only once, and the actual image data inside the .murlpkg file is stored as a WEBP image in our case. If this attribute is not specified, the input stream format is used and no stream format conversion takes place.
  • outputPixelFormat: This attribute defines the actual pixel format that is used for the stored image, when using the PNG or WEBP output stream format. Currently, available values from the IEnums::PixelFormat enumeration are "R8_G8_B8" and "R8_G8_B8_A8".
  • outputCompressionType: When selecting WEBP as the output stream format, this attribute defines the output image's internal compression type from the IEnums::CompressionType enumeration. Available values are "LOSSLESS" and "LOSSY".
  • outputCompressionQuality: This also applies to the WEBP output stream format only, and specifies a quality factor used for encoding. Possible values range from 0 to 100, with higher values resulting in better quality, but also in larger files.

Image resources are available in form of Resource::IImage objects when accessed from code.

PNG, WEBP and DDS Images

PNG and WEBP images can directly be used by specifying their file names in a <Resource> element via the fileName attribute. With some limitiations this is also valid for DDS images (DirectDraw Surface). All three of these formats are able to store alpha channel (transparency) information. It may occur that the actual pixels present near almost-transparent regions of the image contain some sort of "wrong" color information, which is often the result of an image manipulation program such as GIMP or Photoshop not handling the background matte correctly.

There exist two attributes that can be used to perform some sort of "correction step" during loading the image:

  • matteColor: This attribute can be used to specify a matte color value that is applied to all near-transparent pixels, i.e. with an alpha value near zero.
  • matteThreshold: This attribute specifies the actual matte threshold in the range from 0 to 255. The matte color is applied to all pixels whose alpha value is equal or below the given value, so a threshold of 2 only considers pixels with an alpha value of 0, 1 or 2. The default threshold is 8. Specifying this attribute without matteColor has no effect.
Note
Both of these attributes do not have any effect when the input image does not contain an alpha channel.

JPG Images

Like PNG, WEBP and DDS images, JPG images can also be used directly via a resource element's fileName attribute. Note however, that JPG images, while providing good compression on a lossy basis, cannot store alpha information. If you need both, you should consider saving your images in the increasingly popular WEBP format.

PVR Images

PVR (or, more precisely, PVRTC) images are a special case as they provide compressed image data that can directly be used without having to decompress them to memory at first. PVR images have a high compression rate and usually take up only a fraction of memory compared to other formats.

However, only certain graphics processors do support this format, specifically the PowerVR chips from Imagination Technologies (imgtec.com) which can be typically found in mobile devices.

If you decide to use PVR images in your application, you should make sure that these images are only used on those devices that support them. In other words, you should provide a fall-back image for any other devices, e.g. by defining two resources using the same ID, but different conditions:

<Resource id="img1" fileName="test.pvr" includeForGpus="POWERVR"/>
<Resource id="img1" fileName="test.png"/>

On the website mentioned above, you should also find the PowerVR SDK in the "Developers" section, which provides tools to create/convert PVRTC images.

Note
PVR images cannot be converted from/to other formats at load time!

XML Images

XML images are a specialty of the Murl Engine. While not directly taking any pixel input data, they can be used to combine other existing images in a useful way.

When implementing advanced rendering techniques, it is often desired that various per-pixel information is packed into a single 4-component (red, green, blue and alpha) texture image as this is usually way more efficient than accessing separate textures from a GPU shader.

Let's say we have the following special-purpose textures that we want to use in e.g. a relief-map shader:

  • A normal map containing X, Y and Z values in the red, green and blue color channels, respectively
  • A height map gray-scale image representing height (elevation) information
  • A specular map image defining the reflectivity at each pixel, stored in the green channel

Hence, we have five relevant components for our shader. When we omit the normal map's Y component (which can easily be recalculated in the shader), we are down to 4 components, which we can pack into a single RGBA image. We decide to pack the normal map's X component into our new image's red channel, the normal map's Z into the green channel, the height map into the blue channel and the specular map into the alpha channel.

We now create an XML file for defining the load-time combination scheme:

<?xml version="1.0" ?>

<Image sizeX="256" sizeY="256">

  <!-- Define input images -->
  <Source id="nrmmap" imageFileName="normal_map.png"/>
  <Source id="hgtmap" imageFileName="height_map.png"/>
  <Source id="spcmap" imageFileName="specular_map.png"/>

  <!-- Red and green channels receive normal X (red) and Z (blue) -->
  <Destination destinationComponent="RED" sourceId="nrmmap" sourceComponent="RED"/>
  <Destination destinationComponent="GREEN" sourceId="nrmmap" sourceComponent="BLUE"/>

  <!-- Blue channel receives height map (gray scale, any component we like) -->
  <Destination destinationComponent="BLUE" sourceId="hgtmap" sourceComponent="RED"/>

  <!-- Alpha channel receives green channel from specular map -->
  <Destination destinationComponent="ALPHA" sourceId="spcmap" sourceComponent="GREEN"/>

</Image>

The individual files specified via the imageFileName attribute are referenced relative to the image XML file itself. If we want to use our new XML image in a resource package, we can simply write

<Resource id="img1" fileName="combo_image.xml"/>

assuming in our case that the package.xml, combo_image.xml and PNG files are all in the same folder on disk.

Note
The individual input images do not need to have identical dimensions. In our example, by specifying the <Image> element's sizeX and sizeY attributes, we are explicitly setting the size of the output image to 256x256 pixels. If sizeX is not given, all input images must have the same width, and the output image also receives that width. The same is true for sizeY and the image height.

If not all four channels ("RED", "GREEN", "BLUE" and "ALPHA") are used as destinationComponent, the left-out channels are zeroed out in the output image.

The matteColor and matteThreshold are also available for XML images (as a step after combining all channels). See the attribute description above for details.

Atlas Resources

Basically, an atlas resource object is a collection of one or more individual rectangles. Each rectangle stores the following 32bit floating-point values:

  • Start and end screen coordinates in X direction
  • Start and end screen coordinates in Y direction
  • Start and end texture coordinates in X direction
  • Start and end texture coordinates in Y direction

Thus, each rectangle stores 8 individual values in total. The rectangles themselves are indexed from 0 to (n-1).

By itself, an atlas and its rectangles do not have any specific meaning; atlases can basically be used for any suitable purpose. One such purpose is to select rectangular sub-regions of a Graph::FlatTexture for rendering via a Graph::PlaneSequenceGeometry, which is explained in Tutorial #08: Animated Images.

Atlas resources are available in form of Resource::IAtlas objects when accessed from code.

XML Atlases

XML Atlas resource files are recognized by their <Atlas> root element. Individual rectangles can be defined as direct children of the root element using the <Rectangle> element, which accepts the following attribute combinations for defining screen coordinates in X direction:

  • coordX1 and coordX2: Range from X1 to X2
  • coordX1 and coordSizeX: Range from X1 to (X1 + SizeX)
  • coordSizeX and coordX2: Range from (X2 - SizeX) to X2
  • coordOffsetX and coordSizeX: Range from (OffsetX - SizeX / 2) to (OffsetX + SizeX / 2)

By replacing the "X" with a "Y" the same rules apply for screen coordinates in Y direction. For defining texture coordinates, the following attribute combinations are accepted in X direction:

  • texCoordX1 and texCoordX2: Range from X1 to X2
  • texCoordX1 and texCoordSizeX: Range from X1 to (X1 + SizeX)
  • texCoordSizeX and texCoordX2: Range from (X2 - SizeX) to X2
  • texCoordOffsetX and texCoordSizeX: Range from (OffsetX - SizeX / 2) to (OffsetX + SizeX / 2)

Again, the same is true in Y direction. Here is a simple example of an atlas XML file:

<?xml version="1.0" ?>

<Atlas>
    
    <Rectangle texCoordX1="0"   texCoordY1="0" texCoordX2="64"  texCoordY2="64"/>
    <Rectangle texCoordX1="64"  texCoordY1="0" texCoordX2="128" texCoordY2="64"/>
    <Rectangle texCoordX1="128" texCoordY1="0" texCoordX2="192" texCoordY2="64"/>
    <Rectangle texCoordX1="192" texCoordY1="0" texCoordX2="256" texCoordY2="64"/>
    <Rectangle texCoordX1="256" texCoordY1="0" texCoordX2="320" texCoordY2="64"/>
    <Rectangle texCoordX1="320" texCoordY1="0" texCoordX2="384" texCoordY2="64"/>
    <Rectangle texCoordX1="384" texCoordY1="0" texCoordX2="448" texCoordY2="64"/>
    <Rectangle texCoordX1="448" texCoordY1="0" texCoordX2="512" texCoordY2="64"/>
    
</Atlas>
Note
The actual screen and texture coordinate ranges are also not restricted by nature. In the example above all texture coordinates have integer values, i.e. to be able to use these values for rendering a non-repeated texture image, these values must first be normalized to "GPU-friendly" values. For Graph::PlaneSequenceGeometry nodes, this can be accomplished by setting a texture reference size via its textureSizeX and textureSizeY attributes as shown in Tutorial #08: Animated Images.

Font Resources

Font resources provide a mechanism for rendering bitmap fonts using the Murl Engine. By design, a font resource does not actually contain any bitmap or image data, it merely defines where a specific glyph image for a given Unicode character can be found on an accompanying image resource for any number of given characters. In fact, a font resource is only useful in direct combination with a matching image.

Internally, a font resource is similar to an atlas resource. A font resource also stores individual rectangles containing screen and texture coordinates, but with extra information about the Unicode index and the correct alignment of the text on screen.

Font resources are available in form of Resource::IFont objects when accessed from code.

Native Fonts

Native fonts are currently the only type of font resource available in form of binary files with the extension .murl. To create such a file, the Font Converter tool can be used, which basically produces a native .murl font resource file together with a corresponding image containing all necessary glyph images.

See Tutorial #01: Bitmap Fonts for an explanation of how bitmap fonts can be created and used.

Animation Resources

Animation resources provide a way to automatically modify different graph node properties, such as transform position/rotation, material colors or sound volume. Animations are basically made up from individual key frame entries, each defining some specific property value at a given time. Additionally, each such key frame may specify an interpolation mode that is used for calculating the actual property values between two subsequent key frames.

Animation resources are available in form of Resource::IAnimation objects when accessed from code.

Please note that beside Resource::IAnimation objects also Logic::Animation objects like Logic::AnimationReal, Logic::AnimationUInt32, Logic::AnimationVector etc. are available, which can be used for pure code based animations.

Key Types and Instances

Animation keys are derived from the Resource::IAnimation::Raw::Key base structure and are available for a number of different data types.

Scalar Keys

The BoolKey type represents a single Boolean value (true/false). The following properties are controlled by Boolean keys:

Example XML-Animation: 

    <VisibleKey time="0.0" value="false"/>
    <ActiveKey  time="0.0" value="false"/>

The IntegerKey type represents a single signed 32bit integer value. Currently, the following two properties are controlled by integer keys:

Example XML-Animation: 

    <IndexKey       time="0.0" value="31"/>
    <DepthOrderKey  time="0.0" value="2"/>

The FloatKey type defines a single 32bit floating-point value, which is used by the following property:

Example XML-Animation: 

    <VolumeKey time="0.0" value="1.0"/>

Color Keys

The ColorKey type contains four individual 32bit floating-point values, one for each available color component (red, green, blue and alpha). Values usually range from 0.0 (no intensity) to 1.0 (full intensity), but are allowed to lie outside this range for special purposes. The following properties are controlled by color keys:

Note
Note however, that Light nodes do not have an emissive component, so this only has effect on FixedParameters.

Example XML-Animation: 

    <AmbientColorKey  time="0.0" color="1.00f, 1.00f, 1.00f, 1.00f"/>
    <DiffuseColorKey  time="0.0" color="1.00f, 1.00f, 1.00f, 1.00f"/>
    <SpecularColorKey time="5.0" color="1.00f, 1.00f, 1.00f, 1.00f"/>
    <EmissiveColorKey time="5.0" color="0.00f, 0.00f, 0.00f, 0.00f"/>

Transform Keys

The PositionKey type specifies a position in 3-dimensional space with one 32bit floating-point value for each of the three available axes (X, Y and Z):

  • PositionKey Instances manipulate the position component of the Graph::ITransformable's matrix retrieved via GetTransform(). See the inheritance diagram on the reference page for available node classes.

Example XML-Animation: 

    <PositionKey time="0" posX="0" posY="0" posZ="-16.547734"/>

The AxisAngleKey type represents a rotation in 3-dimensional space, with three individual 32bit floating-point values defining the rotation axis (X, Y and Z), and a fourth for defining the rotation angle in radians. The axis is normalized to unit length.

  • AxisAngleKey Instances manipulate the rotation component of the Graph::ITransformable's matrix retrieved via GetTransform(). See the inheritance diagram on the reference page for available node classes.

Example XML-Animation: 

    <RotationKey time="0.0" axisX="1" axisY="0" axisZ="0" angle="45deg"/>

The EulerAngleKey type represents an alternative way to specify a 3-dimensional space rotation, given by three individual 32bit floating-point values defining the euler rotation angles for the three main axis X, Y and Z. Optionally the order of the rotations can be specified with the parameter rotationOrder. Note that it is not allowed to mix AxisAngleKeys, EulerAngleKeys and QuaternionKeys in the same animation resource.

  • EulerAngleKey Instances manipulate the rotation component of the Graph::ITransformable's matrix retrieved via GetTransform(). See the inheritance diagram on the reference page for available node classes.

Example XML-Animation: 

    <RotationKey time="0.0" angleX="12deg" angleY="45deg" angleZ="0deg" rotationOrder="ZYX"/>

The QuaternionKey type represents an alternative way to specify a 3-dimensional space rotation, given by four individual 32bit floating-point values for each quaternion component (Real component R, and imaginary components I, J and K). Note that it is not allowed to mix AxisAngleKeys, EulerAngleKeys and QuaternionKeys in the same animation resource.

  • QuaternionKey Instances manipulate the rotation component of the Graph::ITransformable's matrix retrieved via GetTransform(). See the inheritance diagram on the reference page for available node classes.

Example XML-Animation: 

    <RotationKey time="0.0" quatR="0.0" quatI="0.0" quatJ="1.0" quatZ="0.0"/>

The ScalingKey type defines a scale factor in 3-dimensional space, again with one 32bit floating-point value for each of the three available axes (X, Y and Z):

Example XML-Animation: 

    <ScalingKey time="0.0" scaleZ="0.001" scaleY="0.001" scaleX="0.001" interpolation="SMOOTHSTEP_OUT"/>

XML Animations

Defining actual animation keys can be done by using XML animation resource files, which are recognized by their <Animation> root element. This root element accepts two attributes:

  • startTime and
  • endTime

These attributes define the animation's actual time span relevant when playing back using a Graph::Timeline node. Both attributes represent time values in seconds.

Individual key frame elements may be defined as direct children of the root element. For each of the key instances described above, there is a matching XML tag that can be used to create a key frame element. For all of these, there are two common attributes:

  • The time attribute defines the actual time stamp of the key frame element, again in seconds.
  • The interpolation attribute can be used to specify the actual interpolation mode used to calculate values between the key frame element and its successor (i.e. the next key frame element of the same type). Available string values can be looked up in the Murl::IEnums::Interpolation enumeration.
Note
If the interpolation attribute is not specified, a default value is used that depends on the actual key frame type (see below for details).

Here is a list of all available key frame tags/elements that can be used in an XML animation resource:

Boolean Keys

Boolean key elements are available through the following elements with the default interpolation mode "CONSTANT":

They provide a single attribute:

  • value accepts either one of the string values "1", "true" or "yes" for setting the Boolean value to true, and either one of "0", "false" or "no" for setting the Boolean value to false (case insensitive).

Integer Keys

There are two integer key elements available with the default interpolation mode "LINEAR":

Integer key elements also provide a single attribute:

  • value accepts a string representing a signed 32bit integer value in the range from "-2147483648" to "2147483647".

Floating-point Keys

There is also only one floating-point key element available with the default interpolation mode "LINEAR":

Floating-point keys again provide one single attribute:

  • value accepts a string representing a 32bit floating-point value.

Color Keys

There are four color key elements with the default interpolation mode "LINEAR":

The following attribute is accepted:

  • color expects the string representation of a color value. The following table shows different notations, with the example representing a color value of 0% red, 50% green, 75% blue and 100% alpha:
    Suffix Range Type Example Format
    f 0.0 – 1.0 floating-point "0f, 0.50f, 0.75f, 1f" RGBA / RGB
    i 0 – 255 integer "0i, 128i, 191i, 255i" RGBA / RGB
    h 00 – FF 8 bit hex int "0h, 80h, BFh, FFh" RGBA / RGB
    h 0 – FFFFFFFF 32 bit hex int "FF0080BFh" ARGB / RGB

Position Keys

There is exactly one key element available with the default interpolation mode "LINEAR":

Position key elements accept the following attributes:

  • posX, accepting a string representation of a 32bit floating point value for the X coordinate in 3-space.
  • posY, the same for the Y coordinate and
  • posZ, for the Z axis.

Rotation Keys (AxisAngle, EulerAngle and Quaternion)

There is also exactly one key element available, with default interpolation mode "LINEAR":

Rotation key elements accept the following group of attributes to define the rotation in euler angle format:

  • angleX, accepting a float string value for the rotation angle of the X axis in radians or degrees (suffices 'rad' and 'deg', respectively), performing a clockwise rotation around the given axis.
  • angleY, the same for the Y axis and
  • angleZ, for the Z axis.
  • rotationOrder accepting an IEnums::RotationOrder enumeration string value which defines the axis rotation order, the default order is "ZYX".

Rotation key elements accept the following group of attributes to define the rotation in axis/angle format:

  • axisX, accepting a 32bit floating-point string value for the X coordinate of the normalized rotation axis in 3-dimensional space.
  • axisY, the same for the Y axis and
  • axisZ, for the Z axis.
  • angle, accepting a float string value for the rotation angle in radians or degrees (suffices 'rad' and 'deg', respectively), performing a clockwise rotation around the given axis.

Alternatively, also the following group of attributes is available to define the rotation as a quaternion:

  • quatR, accepting a 32bit floating-point string value for the quaternion's R component
  • quatI, the same for the I component,
  • quatJ, J component and
  • quatK, K component.
Note
All 3 variants can only be used in a mutually exclusive way per key element and animation.

Scaling Keys

There is also exactly one key element available with the default interpolation mode "LINEAR":

Scaling key elements accept the following attributes:

  • scaleX, accepting a string representation of a 32bit floating-point value for the scaling factor in X direction.
  • scaleY, the same for the Y direction and
  • scaleZ, for the Z axis.

The XML Animation Resource Tags page shows a list of nodes and the animation keys they react on, together with the default interpolation used.

The following example shows a complete XML animation file containing both diffuse color keys and scaling keys:

<?xml version="1.0" ?>

<Animation startTime="0.0" endTime="0.5">

    <DiffuseColorKey time="0.0"  color="0.3f, 1.0f, 1.0f, 1.0f"/>
    <DiffuseColorKey time="0.25" color="128i, 128i, 128i, 128i"/>
    <DiffuseColorKey time="0.5"  color="ffffffffh"/>

    <ScalingKey time="0.0"  scaleX="1.0" scaleY="1.0" scaleZ="1.0"/>
    <ScalingKey time="0.25" scaleX="0.9" scaleY="0.9" scaleZ="1.0"/>
    <ScalingKey time="0.5"  scaleX="1.0" scaleY="1.0" scaleZ="1.0"/>

</Animation>

Usage

One way to use an animation resource is to reference it via a Graph::IAnimationTimeController attached to a graph node. Attaching such a controller with a given animation resource to a node can e.g. be done in the following way from within an XML graph resource file:

    <PlaneGeometry controller.animationResourceId="MyPackage:MyMoveAnim1"/>

As can be seen above, the various key instances act on different graph property interfaces. If an animation resource contains key instances that act on a number of different interfaces, and this animation is used on a node that does not implement all of these interfaces, only the relevant keys are used for controlling that node. Example: If an animation, containing both volume and diffuse color keys, is attached to a Graph::Light node, only diffuse color is used and volume is ignored.

As a consequence, this behavior may be used to combine different key instance types into one single animation that is then used for multiple different nodes with each of these nodes only considering animation data relevant to itself.

By default, an IAnimationTimeController evaluates all relevant keys present in an animation with respect to the node it is attached to. In other words, if e.g. an animation contains ambient, diffuse and specular color keys and that animation is used in a Graph::Light node, the controller always manipulates all three properties. This behavior can be changed however to restrict the controller to only a sub-set of the given animation key instances. In our case, to prevent evaluation of the ambient color property and only use the diffuse and specular color keys, we can write:

    <Light 
        controller.animationResourceId="MyPackage:ColorAnim1"
        controller.animationKeys="DIFFUSE_COLOR,SPECULAR_COLOR"
    />

As we can see, the controller.animationKeys attribute accepts a comma-separated list of IEnums::AnimationKey enumeration string values defining the actual key types to act on.

See also Tutorial #08: Animated Images on how to create and use animation resources in your application.

Audio Resources

Currently, the Murl Engine supports two audio file formats: Microsoft/IBM WAVE (.wav) files and OGG-Vorbis files (.ogg). Both can be used directly by specifying their file names in a <Resource> element via the fileName attribute.

Audio resources are available in form of Resource::IAudio objects when accessed from code.

Mesh Resources

Coming soon!

Shader Resources

Coming soon!

Binary Resources

Often it may be necessary to include arbitrary resources in a package, e.g. a simple text file, a custom binary file or an HTML file. Also, if you are directly including e.g. a DDS image file, this image is internally recoded to a PNG image upon package loading for optimization purposes, which may not be desired.

For both cases, such resources may be included in binary form, i.e. directly copied to the package byte by byte. To do so, the resource must be defined in the following way inside the package.xml file:

<Resource type="BINARY" id="MyTextResource" fileName="test.txt"/>
<Resource type="BINARY" id="MyBinaryImageResource" fileName="image.dds"/>

Binary resources are available in form of Resource::IBinary objects when accessed from code.

Text Resources

Unlike all other resources described in the previous sections, text resources do not reference a given file. Instead, text is directly defined as a string inside a package.xml file, using a <Text> element with the value attribute:

<Text id="MyFirstText" value="This is my first resource text string!"/>

Note that you have to escape the following characters, which have a special meaning in XML:

Character XML-Entity
------------------------
" &quot;
' &apos;
< &lt;
> &gt;
& &amp;

The Resource::ICollection object can be used to obtain the text resource.

Example: 

const String& GetResourceText(const Logic::IState* state, const String& resourceId)
{
    const Resource::ICollection* resourceCollection = state->GetResourceCollection();
    if (resourceCollection != 0)
    {
        const Resource::IText* textResource = resourceCollection->GetText(resourceId);
        if (textResource != 0)
        {
            return textResource->GetValue();
        }
    }
    return Util::StaticEmptyString();
}

String text1 = GetResourceText(state, "package_main:MyFirstText");

The Logic::IState object already provides this method.

Example: 

String text1 = state->GetResourceText("package_main:MyFirstText");


Copyright © 2011-2024 Spraylight GmbH.