概述
XGen 提供了 Python API,可以从 Python 壳访问内部 XGen 数据。可以在 Maya 内部或外部使用该 API。此 API 在 Maya 进行扩展,以允许适用于 Maya 但是不适用于其他位置的操作(例如,接受导向的“名称”以获得其面片)。与
XGen 的所有交互应该通过此 API 或 UI 实现。不保证通过 XGen 中存在的 MPxCommand 或 MEL 函数的任何访问。
在下面以伪语法的形式列出了这些方法,以表示返回类型和预期参数类型。调用这些方法的方式与 Python 中的普通操作相同。您可以按照顺序传递这些参数,或者使用这些名称并按照需要重新排序。
导入 API
API 分为两个部分:基本和 Maya。虽然有单独的 UI 组件,但 API 本质上是由基本 C++ 代码、构成基础 API 的 Python 层以及另一个 Python 层(该层提供必要 Maya 附加部分以及组成 Maya API 的额外
API 函数)。务必为该任务提供正确的 API,否则可能会得到意外结果。最佳方法是让 XGen 处理该决定:
这会引入 xgen 模块,该模块可检测 Maya,并根据需要提供 API 的 Maya 层。如果在 Maya 中和 Maya 外运行脚本,并从 API 的仅限 Maya 部分调用方法,您应该将这些方法放在一个条件块中。安全的处理方式是使用 XGen
的 Maya 检测:
import xgen.xgGlobal as xgg
if xgg.Maya
# Do something maya specific like using XGen's Maya API
这会引入 XGen 全局模块,它可以检测 Maya。在放置该模块后,可以使用其 xgg.Maya 变量,以确定是否处于 Maya 中,并在这些条件句中保护您的 Maya 代码。
基础 API
无论在 Maya 的内部还是外部,都可以使用以下方法。它们直接在基本 XGen 数据上操作。如果需要到 XGen 的更快链接,许多还可通过 libXgAPI.so 库作为 C++ API 获得。
创建和删除
- string createDescription( string palette, string description, string primitive, string generator, string renderer, string method )()
- 创建新的描述,然后将其放置在命名的选项板中。如果该选项板不存在,则也会创建它。
- bool deletePalette( string palette )()
- 删除命名的选项板。这将删除其所有描述、面片、对象、fx 模块、导向等等。
- bool deleteDescription( string palette, string description )()
- 删除命名的描述。这将删除其所有面片、对象、fx 模块、导向等等。
对象访问
- string[] palettes()
- string[] descriptions( string palette="" )()
- 获取给定选项板的描述列表;或者,如果没有给定选项板名称,返回场景中的所有描述。
- string palette( string description )()
- 获取给定描述的选项板。要执行此操作,将搜索每个选项板的描述列表,此操作假定所有描述具有唯一名称。
- string getActive( string palette, string description, string type )()
- 从描述获取给定类型的活动子类型。返回值是子类型(例如,SplinePrimitive、CardPrimitive)。
- bool setActive( string palette, string description, string subtype, bool previewer=False )()
- 设置描述的给定类型的活动子类型。给定子类型应完全命名(例如,CardPrimitive、FileRenderer)。
- string[] objects( string palette, string description, bool activeOnly=False )()
- 获得描述的所有对象(例如,SpherePrimitive、GuideRenderer)的列表。
- bool initInterpolation( string palette, string description, string fileName="" )()
- 为给定描述的活动基本体初始化插值。每次将导向移动到新位置、添加导向或者移除导向后,就需要执行此操作。
属性访问
- bool attrExists( string attrName, string palette, string description="", string object="" )()
- string getAttr( string attrName,string palette, string description="", string object="" )()
- bool setAttr( string attrName, string value, string palette, string description="", string object ="")()
- string[] attrs( string palette, string description="", string object="" )()
- void addCustomAttr( string attrName, string palette, string description="", string object ="")()
- 添加自定义属性。该属性应该使用此模板方案命名:custom_<type>_<name> 或 custom_<type>_<name>[#]。如果使用 [#] 扩展名指定一个阵列,则将为每个数组的元素添加一个属性。常见的用法是将属性添加到选项板或 RenderMan 渲染器,但可以指定任何对象。
- void remCustomAttr( string attrName, string palette, string description="", string object="" )()
- 移除自定义属性。该属性应该使用此模板方案命名:custom_<type>_<name> 或 custom_<type>_<name>[#]。如果使用 [#] 扩展名指定一个阵列,则将删除该阵列的所有属性。
- string[] customAttrs( string palette, string description="", string object="" )()
- string[] allAttrs( string palette, string description="", string object="" )()
FX 模块
- string[] fxModules( string palette, string description)()
- 获得给定选项板和描述的 fx 模块列表。会按照执行顺序返回当前活动基本体的模块。
- string fxModuleType( string palette, string description, string name )()
- 获取给定 fx 模块的类型。搜索该模块的活动基本体。
- string addFXModule( string palette, string description, string type, string name="" )()
- 将新的 fx 模块添加到给定描述的活动基本体的 fx 链的末端。如果已成功添加该模块,则将返回其名称。如果失败,则返回空字符串。
- bool removeFXModule( string palette, string description, string name )()
- 从给定描述的活动基本体删除命名的 fx 模块。如果成功,则返回值为“真”,如果失败,返回值为“假”。
- bool moveFXModule( string palette, string description, string name, int dir )()
- 移动 FX 模块。将使用该模块名称找到给定描述的活动基本体中的模块。一旦找到,该模块将上移或下移,具体取决于“方向”的值。负值表示“向上”,正值表示“向下”。
消隐
- string[] culledPrimPatches( string palette, string description )()
- 如果给定选项板和描述,则返回具有已消隐的基本体的面片的名称。
- int[] culledPrimFaces( string palette, string description, string patchName )()
- 如果给定选项板、描述和面片名称,则返回具有已消隐的基本体的面片上的面。
- set(int) culledPrims( string palette, string description, string patchName, int faceId )()
- 指定一个选项板、描述、面片名称和面 ID,将返回该面上的消隐的基本体 ID。
绑定信息
- string[] boundGeometry( string palette, string description )()
- 指定选项板和描述,返回所有绑定几何体块的名称。在 XGen 中,这些同时也是面片名称。
- int[] boundFaces( string palette, string description, string patchName )()
- 指定选项板、描述和面片名称,返回绑定到该面片的描述的面的列表。
文件 IO
- string importPalette( string palette, string deltas[], string nameSpace="" )()
- 应用指定的增量文件后,从一个 xgen 文件导入选项板。可以选择将选项板放入给定名称空间。在 Maya 中,有一个可选的第四个参数,称为 wrapPatches,其默认值为“真”(True)。将此值设置为“假”(False),则允许您引入一个选项板,而不加载其面片或导向。执行此操作,您可以引入不包含几何体的选项板,可以将其用作引用,传输到另一个元素等等。
- bool exportPalette( string palette, string fileName )()
- int createDelta( string palette, string newDelta )()
- 将 Maya 中加载的当前选项板与增量文件列表应用后的基础选项板比较,将差异写入新的增量文件中。如果一个文件编写成功,则函数返回 1,如果成功但是没有编写任何文件(没有发现差异)则返回 0,如果出现错误则返回 -1(发现增量文件的无效更改)。
- bool applyDelta( string paletteName, string delta )()
- string importDescription( string palette, string fileName )()
- 从 xdsc 文件导入描述并插入到选项板中。将此描述放入选项板的名称空间中。将还原描述使用的任意选项板的表达式。如果存在名称冲突,则将新描述的表达式的值放入选项板表达式中,而将旧值放入该表达式的注释。
- bool exportDescription( string palette, string description, string fileName, bool guides = false )()
- 从选项板将描述(包括可能使用的任何选项板的表达式)导出到 xdsc 描述文件。导向标志将被保留,且当前未使用。
- string importFXModule( string palette, string description, string fileName )()
- 从 xgfx 文件导入 FX 模块,并插入到给定描述的活动基本体。
- bool exportFXModule( string palette, string description, string name, string fileName )()
事件回调
- registerCallback( string name, string function )()
- 注册发生命名的 XGen 事件时调用的函数。事件类型:PrePaletteCreate、PostPaletteCreate、PreDescriptionCreate、PostDescriptionCreate 和 CurrentDescriptionSet。
- deregisterCallback( string name, string function )()
消息
- setMessageLevel( string type, int level )()
- 设置给定类型消息的详细级别。类型可以是调试、警告、统计信息或 quitOnError。对于前三种类型,可以将级别设置为 0 到 5,其中 5 最详细。对于 quitOnError,可以设置一个布尔值,其中 1 为打开,0 为关闭。
- int getMessageLevel( string type )()
- 获取给定类型的消息的详细级别。类型可以是调试、警告、统计信息或 quitOnError。对于前三种类型,返回的级别为 0 到 5,其中 5 最详细。对于 quitOnError,返回的级别分别是 1 和 0,分别表示打开和关闭。
一般功能
- string version()
- string rootDir()
- string iconDir()
- string globalRepo()
- string localRepo()
- string userRepo()
- string promoteFunc()
- string objNameSpace( string name )()
- string stripNameSpace( string name )()
- string prepForAttribute( string value )()
- 如果给定的字符串包含嵌入换行符和制表符,此函数将使用这些字符的编码版本逐一替换。这样就可以将字符串存储在一行中,要存储在 XGen 文件中或者在描述编辑器中进行编辑,必须符合此要求。此函数如果结合使用 prepForEditor,则允许使用往返字符串格式和属性存储。
- string prepForEditor( string value )()
- 如果给定的字符串具有编码制表符和换行符,此函数将转化字符串,以还原这些字符,这样字符串可以用于多行文本编辑器。这允许将编码字符串恢复为针对该编辑器的原始格式。此函数如果结合使用 prepForAttribute,则允许使用往返字符串格式和属性存储。
Maya 扩展 API
Maya 提供了所有的基础 API 方法,但以下方法进一步扩展了 API。这些 API 不作为基础 API 的一部分提供的原因通常是在该上下文中没有意义。例如,如果一个方法在 Maya 中接受“导向名称”,并返回“面片名称”,则不适用于标准 XGen,因为其中导向没有名称,而面片只是以其几何体命名。也就是说,许多基础
API 方法在 Maya 中被覆盖,因此如果在 Maya 中,您应该始终通过 Maya API 引用该 API,以确保引用正确的层。
- string guidePatch( string guide )()
- string guideDescription( string guide )()
- string guideIndex( string guide )()
- string[] descriptionGuides( string descr )()
- string[] descriptionPatches( string descr )()
- string[] palettePatches( string palette )()
- string[] geometryPatches( string geometry )()
- string[] geometriesPatches( string geomList[] )()
- 获取绑定到列表中任何几何体的面片。如果按顺序使用一系列几何体,此函数比调用 geometryPatches 有效。
- string geometryDescriptionPatch( string geometry, string desc )()
- string[] geometryFacePatches( string geometry, string faceId )()
- 给定一块几何体和面 ID,返回与该面相关的所有面片。
- modifyFaceBinding( string palette, string description, string mode="Append" )()
- 修改当前描述的面绑定。在“附加”模式下,将选定的面添加到绑定到关联几何体的面片。如果该几何体没有任何面片,则将创建一个新面片。在“替换”模式下,选定的面将替换这些关联几何体的面片中的面。最后,在“移除”模式中,如果存在面片,则会从关联几何体的面片中移除这些面。如果生成的面片没有绑定面,则面片将被删除。
- fixPatchNames( string palette )()
- 更新选项板中所有面片的名称。如果描述重命名,或者描述绑定到的几何体重命名,则必须同时更新这些面片的名称。
- string nodeClass( string node )()
- 如果给定 Maya 节点,返回 XGen 对象的常规类。如果节点不是 XGen 对象,则返回“无”(None)。
- bool renderable( string node )()
- 如果对象可以渲染则返回真。这可以用于避免将着色器分配给不可渲染的对象这类问题。
- string[] findSelectedPatches()
- 返回与当前选择列表相关的所有 XGen 面片。导向、面片、描述、几何体等都将解析为相关的面片。
- string[] bakedGroomManagerBake( string pal, string desc )()
- 烘焙当前修饰,直到烘焙修饰管理器的位置。这会为每个包含静态修饰的描述的边界几何体生成一个 XPD 文件。将留下该描述,而烘焙修饰管理器处于活动状态。
- setExportAsDelta( bool value, string pal=None )()
- 控制是否将选项板导出为完整的选项板或增量文件。如果传入的值设为真,则只有当选项板更改时才会为选项板编写增量文件。如果未传入任何选项板,则场景中的所有选项板将设为新值。
Maya MPx API
以下是 MPxCommand,它们是 XGen API 的一部分,只能通过 Maya 获得。
- bool xgmGuideGeom -guide string [-numVertices] [-basePoint | -controlPoints] [-lockBasePt]()
- bool xgmPatchInfo -patch string [-description | -geometry | -faceIds | -rename string]()
- bool xgmBakeGuideVertices [-resetPivots]