resolvePath

void resolvePath(
    const std::string& str, 
    const int frame, 
    std::string& ret
)

This function should resolve any assetId, environment variables, and expand user directories referenced with a ~ tilde. It should also use the current FileSequence plugin to resolve file sequence patterns in the filename.

The str argument does not need to be an assetId, but it can be. It can be any string that is intended to be used as a file path. It may already be a perfectly valid, resolved file path that doesn't need any modifications.

The resulting string must always be copied into the ret argument. If the incoming str has nothing to do with file paths, the incoming string must be copied to ret without changed.

This method does more work than than resolveAsset or resolveAllAssets.

This function will likely need to maintain a cache to perform well. While rendering a typical scene, it will be called thousands and millions of times over most strings being sent to the renderer. This includes whitespace only data, LUA code, and every string going to the renderer. Katana will pass the same attribute values repeatedly each time they are found in the scenegraph.

Foundry's provided examples and default asset plugin source code have reasonable examples of substituting environment variables. Running the frame sequence plugin can be done with a couple of lines that look like:

    if (FnKat::DefaultFileSequencePlugin::isFileSequence(path))
    {
        path = FnKat::DefaultFileSequencePlugin::resolveFileSequence(path, frame);
    }

This function is used extensively while resolving procedural and material attributes for rendering. It will also be called by the LookFileManager node. Attribute scripts have an AssetResolve function and parameter expressions define resolvePath that both pass their arguments to this plugin method.

Be aware that this will also be passed scenegraph locations which look similar to file paths. It may be wise to ignore all strings that start with /root/ and copy them to ret unaltered.

When Katana opens a file for interactive editing, it will often call this method on an assetId that has no version. It is up to this function to determine the best version for loading and resolve that file path for a .katana file.