Content Preprocessing

Unlike some alternative frameworks, Ultraviolet's content pipeline processes assets entirely at runtime. When dealing with large or complicated assets, this can lead to long loading times; file formats which are convenient for artists and developers may not always be the most efficient way to represent the data in question, placing an unnecessary computational burden on the game engine. To address this problem, Ultraviolet allows content files to be preprocessed into a format more readily suited for quick loading.

Preprocessing Assets

Content preprocessing is performed by the same content processors which are used to load raw assets. Not all content processors support preprocessing; in some cases, there is no obvious way to improve the data over its raw format. Attempting to preprocess files which do not support preprocessing via their standard content processors will have no effect.

To preprocess an asset, use the ContentManager.Preprocess() method.

var assetWasPreprocessed = contentManager.Preprocess<Texture2D>("path/to/MyTexture", true);

// or...

AssetID someAssetID = MyAssetIDs.SomeAsset;
var assetWasPreprocessed = contentManager.Preprocess<Texture2D>(someAssetID, true);

The generic parameter is the type of object, like Texture2D or Song, that the asset represents. The first parameter is the path to the asset to preprocess. The second parameter indicates whether the original, raw asset file should be deleted after preprocessing is complete; if false, the original will remain in place. Even if this parameter is set to true, however, the original file will not be deleted if content preprocessing is not supported by the format in question.

You can preprocess an entire content manifest with a single call:

var manifest = Ultraviolet.GetContent().Manifests["Global"];
contentManager.Preprocess(manifest, true);

This is equivalent to calling Preprocess<T>() on each asset within the manifest individually.

Attempting to preprocess a file which does not exist will throw a FileNotFoundException, but attempting to preprocess a file which has already been preprocessed will simply do nothing and return false to indicate that preprocessing failed.

Preprocessed Files

Preprocessing a file results in the creation of a new file with the same name and the .uvc file extension. When loading assets, preprocessed files are given higher priority by Ultraviolet's content managers than non-preprocessed files with the same name.

As an example, consider the following code, assuming that there exists a texture file named MyTexture.png (in its raw format).

var texture = contentManager.Load<Texture2D>("MyTexture");

Because no file extension has been specified in the asset path passed to Load<T>(), the above code will load MyTexture.uvc if it exists, and MyTexture.png if it does not.

If necessary, you can force Ultraviolet to load the raw file over the preprocessed file by including the file extension:

var texture = contentManager.Load<Texture2D>("MyTexture.png");

Note that assets which have been preprocessed by one version or implementation of the Framework are not guaranteed to be usable by any other version or implementation of the Framework.