Référence des API de script
Cette page décrit les principaux concepts de l’API.
Pour plus d’informations, consultez la documentation livrée avec l’application qui est accessible dans Aide > Documentation de l’API Python…. Dans cette documentation, effectuez une recherche rapide des noms de module (entre parenthèses ci-dessous) pour trouver facilement leur définition.
Contexte
L’objet contexte (Context) est le point d’entrée principal de l’API. Il est créé la première fois que l’utilisateur l’obtient à l’aide de la méthode ‘getContext()’ du module ‘sd’.
Cet objet permet essentiellement de récupérer l’objet application (SDApplication).
Application (SDApplication)
L’application (SDApplication) est l’objet qui permet l’accès aux principaux gestionnaires d’API, tels que :
- le gestionnaire de package Manager (SDPackageMgr) qui gère tous les packages de l’application ;
- Module Manager (SDModuleMgr) qui gère tous les modules de l’application ;
- le gestionnaire d’interface utilisateur (SDUIMgr) qui peut créer des menus et des ancrages dans la fenêtre de l’application.
Vous pouvez enregistrer rappels auprès de l’application qui sera appelée lorsque certains événements se produiront.
Gestionnaire de modules (SDPackageMgr)
Cet objet gère tous les packs de l’application. Les packages sont affichés dans le composant « Explorateur ».
Il permet de :
- créer un nouveau pack ;
- charger/décharger un package ;
- enregistrer un pack ;
- rechercher un pack.
Package (SDPackage)
Un package (SDPackage) est une collection de ressources (SDResource).
Le contenu d’un package peut être stocké dans un fichier avec l’extension .sbs via l’objet ‘SDPackageMgr’. Cet objet vous permet de récupérer des ressources spécifiques.
Pour créer une ressource spécifique, consultez les méthodes statiques d’objet associées (par exemple : ‘SDSBSCompGraph.sNew()’).
Un package contient également un dictionnaire de métadonnées (SDMetadataDict). Vous trouverez plus d’informations sur les métadonnées ici.
Ressource (SDResource)
Une ressource (SDResource) est un objet qui peut être référencé par une autre ressource.
Il existe plusieurs types de ressources :
- Dossiers (SDResourceFolder);
- Graphes (SDGraph);
- Bitmaps (SDResourceBitmap);
- Images de SVG (SDResourceSVG);
- Polices (SDResourceFont);
- Scènes (SDResourceScene);
- Mesures BSDF (SDResourceBSDFMeasurement);
- Profils lumineux (SDResourceLightProfile).
Une ressource peut être créée à partir de la méthode statique ‘sNew()’ sous :
- un colis ;
- un dossier.
Une ressource peut avoir plusieurs propriétés (SDProperty).
Gestionnaire d’interface utilisateur (SDUIMgr)
Le gestionnaire d’interface utilisateur permet de créer des éléments d’interface utilisateur dans la fenêtre principale de la Substance Designer, tels que des menus, des docks et d’enregistrer des rappels à appeler lorsque des événements liés à l’interface utilisateur se produisent.
En outre, le gestionnaire d’interface utilisateur a accès au graphe actif et à la sélection du graphe actif.
Graphes (graphique ODD)
Un graphe (SDGraph) est un objet qui contient :
- nodes (SDNode);
- Objets graphe (SDGraphObjects);
- propriétés (SDProperty).
Il existe 4 types de graphes différents :
- graphe de Substance (SDSBSCompGraph)
- graphe de fonction de Substance (SDSBSFunctionGraph)
- graphe FXMap de Substance (SDSBSFxMapGraph)
Un graphe peut avoir un ou plusieurs nœuds de sortie. Les nœuds de sortie représentent les résultats du graphe.
Tous les nœuds disponibles pour un graphe peuvent être récupérés avec la méthode ‘getNodeDefinitions()’.
Un nouveau nœud peut être créé avec la méthode ‘newNode()’.
Un nouveau nœud instance peut être créé à partir d’une ressource (SDResource) avec la méthode ‘newInstanceNode()’.
Nœud (SDNode)
Un nœud (SDNode) représente une opération effectuée sur un objet.
Il peut être créé à partir de :
- a définition (SDDefinition) (voir 'SDGraph.newNode()');
- a ressource (SDResource) (voir 'SDGraph.newInstanceNode()').
Un nœud peut avoir plusieurs propriétés.
Il existe plusieurs types de nœud :
- SDSBSCompNode : nœud du Graphe Substance (SDSBSCompGraph);
- SDSBSFunctionNode : nœud du Graphe de fonction Substance (SDSBSFunctionGraph);
- SDSBSFxMapNode : nœud du Graphe FXMap de la Substance de données (SDSBSFxMapGraph);
Objets Graphe (SDGraphObjects)
Un objet de graphe (SDGraphObject) est un objet qui ajoute des informations supplémentaires au graphe, mais qui n’est pas pris en compte pendant le processus d’évaluation du graphe.
Il existe 3 types d’objets graphe :
- Épingle (SDGraphObjectPin)
- Commentaire (SDGraphObjectComment)
- Cadre (SDGraphObjectFrame)
Pour plus d’informations sur la création de ces objets, consultez la méthode statique ‘sNew()’.
Propriétés (SDProperty)
Une propriété (SDProperty) est un objet qui décrit une propriété de un autre objet (un graphe, un nœud, une ressource, etc.).
Il appartient à une catégorie spécifique (SDPropertyCategory) :
- Entrée : classe les propriétés d’entrée d’un objet, qui ont généralement un impact sur l’opération effectuée par l’objet actuel ;
- Exemple : la propriété ‘color’ d’un nœud de Couleur uniforme dans un graphe de Substance est une propriété d’entrée ;
- Sortie : classe les propriétés de sortie d’un objet. Il est utilisé pour identifier un résultat d’un objet ;
- Annotation : classe les propriétés qui n’ont pas d’impact sur l’opération effectuée par un objet ;
- Ex. : le ‘label’ d’un graphe est une propriété d’annotation, car il n’a aucune incidence sur le calcul du graphe.
Il contient les membres suivants :
- Id : identifiant de la propriété dans le cadre de cette catégorie ;
- Types : types pris en charge par la propriété actuelle. Certaines propriétés peuvent prendre en charge plusieurs types : ‘int’, ‘float’, etc.;
- Ex. : les propriétés d’entrée d’un nœud ‘sbs::add’ peuvent prendre en charge différents types : 'int’, 'int2’, 'int3’, 'int4’, 'float’, 'float2’, 'float3’, 'float4’, etc.;
- Catégorie : catégorie à laquelle la propriété appartient (entrée, sortie, annotation);
- Libellé : libellé de la propriété, utilisé pour l’affichage uniquement;
- Description : description de la propriété ;
- DefaultValue : valeur par défaut ;
- IsConnectable : indique si une connexion (SDConnection) peut être effectuée sur cette propriété ;
- isReadyOnly : indique si la propriété est en lecture seule. Si la valeur est true, la valeur qui lui est associée ne pourra pas être modifiée ;
- isVariadic : si la valeur est true, cette propriété sera représentée comme propriétés multiples sur l’objet ;
- isPrimary : indique si la propriété spécifiée est la propriété principale qui contrôle d’autres propriétés. Remarque : ceci est spécifique aux nœuds de composition de Substance (SDSBSCompNode).
Exemples :
- Propriétés du nœud ‘sbs::input’ :
- Propriétés du nœud ‘sbs::blend’ :
Type (SDType)
Un type (SDType) contient des informations d’une valeur type, telles que :
-
Id : identifiant du type ;
-
Modificateur : le modificateur de type qui peut être l’une des valeurs 'SDTypeModificateur’ enum :
- Auto;
- Uniforme : la valeur est évaluée une fois par opération ;
- Variation : la valeur est évaluée plusieurs fois par opération (par exemple : pour chaque texel).
Plusieurs types sont définis, tels que :
- enums (SDTypeEnum) : décrit un type enumeration avec toutes ses propriétés ;
- structures (SDTypeStruct) : décrit un type structure avec toutes ses propriétés ;
- array (SDTypeArray) : décrit un array.
- etc.
Voir la documentation de l’API Python de la Substance Designer pour la liste exhaustive.
Valeurs (SDValue)
Une valeur (SDValue) est un objet qui encapsule une valeur de type de base.
Par exemple :
- un objet ‘SDValueInt’ encapsule une valeur ‘int’;
- un objet ‘SDValueFloat4’ encapsule une valeur ‘float4’;
- etc.
La valeur de type de base peut généralement être récupérée avec la méthode ‘get()’, mais cela peut dépendre du type de 'SDValue’ qui a été retourné.
Connexion (SDConnection)
Une connexion (SDConnection) représente un lien entre deux propriétés différentes de deux nœuds différents.
Il contient :
- Le nœud cible;
- propriété cible du nœud cible ;
Toutes les opérations de connexion sont effectuées sur un nœud :
- création d’une nouvelle connexion, voir ‘SDNode.newPropertyConnection()’
- suppression d’une connexion existante, voir ‘SDNode.deletePropertyConnection()’
- récupération des connexions d’une propriété, voir ‘SDNode.getPropertyConnections()’
Module (SDModule)
Un module est une collection de définitions et de types.
Il permet de récupérer facilement toutes les informations sur les nœuds qui peuvent être créés, ainsi que sur les énumérations et les structures.
Il contient :
- un identifiant (Id) unique dans le contexte du gestionnaire de modules (SDModuleMgr);
- une liste de définitions (SDDefinition);
- une liste de types (SDType).
Définition (SddDefinition)
Un objet de définition (SDDefinition) contient des informations sur la définition d’un objet particulier basé sur propriétés (« SDNode », etc.).
Il contient :
- Id : identifiant de la définition ;
- Libellé : libellé de la définition ;
- Description : description de la définition ;
- Propriétés : propriétés de toutes les propriétés disponibles catégories (SDPropertyCategory).