createAssetAndPath

void  createAssetAndPath(
    AssetTransaction* txn, 
    const std::string& assetType,
    const StringMap& assetFields, 
    const StringMap& args, 
    bool createDirectory,
    std::string& assetId)

Called by Katana to create assets before writing files to an assetId. This is called for all write operations like saving the current Katana session, writing live groups, baking materials, and outputting from Render or Write nodes.

This function must return the assetId that will be written to by Katana. This must be copied into the assetId argument.

If the txn argument is "NULL" then this function should operate immediately. The transaction will be provided by createTransaction if provided by this asset plugin. If a transaction is provided, this function can defer creation of the asset until the commit or cancel method is called. When deferring asset creating with a transaction, this function still must return the assetId that will be generated when the transaction is committed.

The assetType is a string enumerated by Katana's asset type constants like kFnAssetTypeLookFile or kFnAssetTypeLiveGroup.

The args is a customizeable collection of information to control asset creation. Common arg values are "versionUp" and "fileExtension". Other values are for specific types of output like "colorspace" used by the when creating kFnAssetTypeImage. Many of these args will come from the hints provided by properties. These same arguments are passed to postAssetCreate.

The createDirectory controls if Katana wants the actual resolved assetId location to exist on disk when this method returns.

If an error occurs, set the assetId to an empty string to indicate a problem. There is no way to inform the caller of what went wrong or why. The code can call FnLogError to at least get information to where someone could see it.

Katana will generate new asset fields by calling getAssetFields on the resulting assetId and passing those fields to createAssetAndPath after writing all files.

The args will often contain a combination of "versionUp" and "publish" values. These are string set to "True" or "False" to indicate a boolean state. When different "Save" operations are initiated from Katana's menu these args will be set as:

# Using "File->Save As" generates args
{'versionUp': 'True', 'publish': 'False'}

# Using "File->Save" generates arg 
{'versionUp': 'False', 'publish': 'False'}

# And "File->Version Up and Save" args are
{'versionUp': 'True', 'publish': 'True'}

# The args for live group publish (with or without "finish editing")
{'versionUp': 'True'}

Katana provides a way for all write operations to provide the additional args. This enables a facilty to add asset specific arguments for tags, labels, and custom states to be passed to the asset api publishes.

When artists are interactively publishing, additional arguments can be defined in the interface created by BaseAssetWidgetDelegate.configureAssetBrowser.

Most write functions in the Katana API accept an optional StringMap (or Python dictionary). These values become the args passed to this and postAssetCreate. For example

    KatanaFile.Save(fileNameOrAssetId, extraOptionsDict=None)
    KatanaFile.Export(fileNameOrAssetId, nodes, extraOptionsDict=None)
    LiveGroup.exportAsset(filenameOrAssetID, extraOptions=None)

This function is combined with createAssetAndPath but the two asset plugin methods are not always called together in the same process at the same time. At some point Katana will call getAssetFields on the resulting assetId and pass them to createAssetAndPath.