How Are Files/Assets/Resources Loaded?

The PowerVR Framework uses the stream abstraction for data. Stream is an abstract class and can be subclassed into a concrete type of stream. Use this to determine your own.

There are four types of concrete stream classes in the SDK:

• BufferStream is a stream that points to a block of RAM. It is used to read and write to memory without a persistent storage. Any block of memory can be pointed to by the buffer, and this class is used when a custom part of memory needs to be passed to a function requiring a Stream.

• FileStream is a file.

• AndroidAssetStream is a stream accessing an .apk’s assets.

• WindowsResourceStream is a stream accessing a Windows executable’s embedded resources.

There are two ways to make use of these.

Use pvr::Shell::getAssetStream(…name…)

This function will look for any applicable methods depending on the platform, and attempt to create a stream with that method, until it succeeds or run out of methods.

The priority from highest to lowest is:

• A FileStream for the determined path, in any of the following folders:

  • The current directory.

  • The directory where the application executable is.

  • The directory Assets_[executable name].

  • Any other paths added through pvr::Shell::addReadPath.

• AndroidAssetStream will look for an asset of the specified name in the .apk’s assets folder.

• WindowsResourceStream will look for an embedded resource of the specified name in the executable.

The parameter passed to getAssetStream is usually a raw filename, or a relative path, but can be anything depending on the use. The convention used is that is a raw executable name, and assumes that window resources are named with this path. Files will be searched in the current folder of the executable and in the Assets_[ExecutableName] subfolder. Functions that need some kind of data to create an object, most notably, asset load functions, will take streams as input. The only exceptions are PVRVk Shaders - these are passed as raw bytes to avoid a PVRVk dependency on PVRCore.

Directly create the stream

The other option is to directly create a FileStream/ BufferStream/ WindowsResourceStream to load a resource. In order to do this, the resource must be of the correct type and be supported on the platform. For example, a FileStream will work fine for Windows and Linux, but on Android it may not be what is expected. Use an AndroidAssetStream to read from an .apk’s assets, while a FileStream will read and write to the application’s temporary location. Finally, in order to pass custom data to a stream function, for example, a std::string into a function that requires a stream, the data can be trivially wrapped using the constructor of a BufferStream.