Asset API (OpScript)
====================

.. lua:module:: Asset

Asset Plugin
------------

.. lua:function:: GetDefaultAssetPlugin()

   Returns an :lua:class:`AssetPlugin` object.

.. lua:class:: AssetPlugin

   Class representing the default asset plugin. Note that this is not
   instantiable directly - instead use :lua:func:`GetDefaultAssetPlugin`.

   In the methods below the optional *throwOnError* boolean flag determines
   whether an exception is thrown in the case of an error.

   .. lua:method:: isAssetId(string str, [boolean throwOnError=false])

      Returns ``true`` if input string represents a valid asset id.

   .. lua:method:: containsAssetId(string str, [boolean throwOnError=false])

      Returns ``true`` if input string contains a valid asset id anywhere
      within it.

   .. lua:method:: checkPermissions(string assetId, table context, \
                                    [boolean throwOnError=false])

      Returns ``true`` if permissions for the given asset id are valid in the
      given context.

   .. lua:method:: resolveAsset(string assetId, [boolean throwOnError=false])

      Look up asset id in asset system and return path (or other string) that
      it references.

   .. lua:method:: resolveAllAssets(string str, \
                                    [boolean throwOnError=false])

      Replace any asset ids found in input string with resolved asset strings.

   .. lua:method:: resolvePath(string path, int frame, \
                               [boolean throwOnError=false])

      Resolves env vars in input path string, then resolves asset ids and file
      sequences.

   .. lua:method:: resolveAssetVersion(string assetId, string versionStr, \
                                       [boolean throwOnError=false])

      Return integer version that this asset id resolves to.

   .. lua:method:: getUniqueScenegraphLocationFromAssetId( \
                      string assetId, boolean includeVersion, \
                      [boolean throwOnError=false])

      Returns a valid scene graph location path that uniquely represents the
      input asset id.

   .. lua:method:: getAssetVersions(string assetId, \
                                    [boolean throwOnError=false])

      Returns a list of the available versions for the given asset.


   .. lua:method:: getRelatedAssetId(string assetId, string relation, \
                                     [boolean throwOnError=false])

      Returns asset id that is related to input asset, given a relationship
      type.

   .. lua:method:: getAssetFields(string assetId, boolean includeDefaults, \
                                  [boolean throwOnError=false])

      Convert from asset id to a table of named string fields defining the
      asset. If includeDefaults is ``true``, include default values for fields
      not explicitly specified by the assetId.

   .. lua:method:: buildAssetId(table fields, [boolean throwOnError=false])

      Convert from asset fields (table with string keys/values) to asset id.

   .. lua:method:: getAssetAttributes(string assetId, string scope, \
                                      [boolean throwOnError=false])

      Get metadata associated with an asset or a scoped item in the asset
      hierarchy.

   .. lua:method:: getAssetIdForScope(string assetId, string scope, \
                                      [boolean throwOnError=false])

      Get asset id scoped to the specified level in the asset hierarchy.

   .. lua:method:: getAssetDisplayName(string assetId, \
                                       [boolean throwOnError=false])

      Produces a name for the given asset that can be used to represent the
      asset in a scene graph location.



File Sequence Plugin
--------------------

.. lua:function:: GetDefaultFileSequencePlugin()

   Returns a :lua:class:`FileSequencePlugin` object.

.. lua:class:: FileSequencePlugin

   .. lua:method:: isFileSequence(string str, [boolean throwOnError=false])

      Returns ``true`` if *str* is a valid file sequence.

   .. lua:method:: buildFileSequenceString(string prefix, string suffix, \
                                           int padding, \
                                           [boolean throwOnError=false])

      Returns file sequence string built from given *prefix*, *suffix*, and
      *padding* values.

   .. lua:method:: resolveFileSequence(string path, int frame, \
                                       [boolean throwOnError=false])

      Resolves a file sequence string into an single real file path.

   .. lua:method:: isFrameInFileSequence(string path, int frame, \
                                         [boolean throwOnError=false])

      Returns ``true`` if *frame* is a part of the file sequence