diff --git a/src/user/user_api.h b/src/user/user_api.h index 40907f47..0682191a 100644 --- a/src/user/user_api.h +++ b/src/user/user_api.h @@ -40,39 +40,39 @@ typedef struct _mjDoubleVec* mjDoubleVec; //---------------------------------- enum types (mjt) ---------------------------------------------- -typedef enum _mjtGeomInertia { // type of inertia inference - mjINERTIA_VOLUME, // mass distributed in the volume - mjINERTIA_SHELL, // mass distributed on the surface +typedef enum _mjtGeomInertia { // type of inertia inference + mjINERTIA_VOLUME, // mass distributed in the volume + mjINERTIA_SHELL, // mass distributed on the surface } mjtGeomInertia; -typedef enum _mjtBuiltin { // type of built-in procedural texture - mjBUILTIN_NONE = 0, // no built-in texture - mjBUILTIN_GRADIENT, // gradient: rgb1->rgb2 - mjBUILTIN_CHECKER, // checker pattern: rgb1, rgb2 - mjBUILTIN_FLAT // 2d: rgb1; cube: rgb1-up, rgb2-side, rgb3-down +typedef enum _mjtBuiltin { // type of built-in procedural texture + mjBUILTIN_NONE = 0, // no built-in texture + mjBUILTIN_GRADIENT, // gradient: rgb1->rgb2 + mjBUILTIN_CHECKER, // checker pattern: rgb1, rgb2 + mjBUILTIN_FLAT // 2d: rgb1; cube: rgb1-up, rgb2-side, rgb3-down } mjtBuiltin; -typedef enum _mjtMark { // mark type for procedural textures - mjMARK_NONE = 0, // no mark - mjMARK_EDGE, // edges - mjMARK_CROSS, // cross - mjMARK_RANDOM // random dots +typedef enum _mjtMark { // mark type for procedural textures + mjMARK_NONE = 0, // no mark + mjMARK_EDGE, // edges + mjMARK_CROSS, // cross + mjMARK_RANDOM // random dots } mjtMark; -typedef enum _mjtLimited { // type of limit specification - mjLIMITED_FALSE = 0, // not limited - mjLIMITED_TRUE, // limited - mjLIMITED_AUTO, // limited inferred from presence of range +typedef enum _mjtLimited { // type of limit specification + mjLIMITED_FALSE = 0, // not limited + mjLIMITED_TRUE, // limited + mjLIMITED_AUTO, // limited inferred from presence of range } mjtLimited; typedef enum _mjtInertiaFromGeom { - mjINERTIAFROMGEOM_FALSE = 0, // do not use; inertial element required - mjINERTIAFROMGEOM_TRUE, // always use; overwrite inertial element - mjINERTIAFROMGEOM_AUTO // use only if inertial element is missing + mjINERTIAFROMGEOM_FALSE = 0, // do not use; inertial element required + mjINERTIAFROMGEOM_TRUE, // always use; overwrite inertial element + mjINERTIAFROMGEOM_AUTO // use only if inertial element is missing } mjtInertiaFromGeom; @@ -84,8 +84,8 @@ typedef struct _mjElement { // element type, do not modify typedef struct _mjSpec { // model specification - mjElement* element; // object type - mjStatistic stat; // statistics override (if defined) + mjElement* element; // element type + mjString modelname; // model name // compiler settings mjtByte autolimits; // infer "limited" attribute based on range @@ -109,33 +109,33 @@ typedef struct _mjSpec { // model specification mjLROpt LRopt; // options for lengthrange computation // engine data - mjString modelname; // model name - mjOption option; // options - mjVisual visual; // visual options - size_t memory; // size of arena+stack memory in bytes - int nemax; // max number of equality constraints - int njmax; // max number of constraints (Jacobian rows) - int nconmax; // max number of detected contacts (mjContact array size) - size_t nstack; // (deprecated) number of fields in mjData stack - int nuserdata; // number extra fields in mjData - int nuser_body; // number of mjtNums in body_user - int nuser_jnt; // number of mjtNums in jnt_user - int nuser_geom; // number of mjtNums in geom_user - int nuser_site; // number of mjtNums in site_user - int nuser_cam; // number of mjtNums in cam_user - int nuser_tendon; // number of mjtNums in tendon_user - int nuser_actuator; // number of mjtNums in actuator_user - int nuser_sensor; // number of mjtNums in sensor_user + mjOption option; // physics options + mjVisual visual; // visual options + mjStatistic stat; // statistics override (if defined) // sizes - int nkey; // number of keyframes + size_t memory; // number of bytes in arena+stack memory + int nemax; // max number of equality constraints + int nuserdata; // number of mjtNums in userdata + int nuser_body; // number of mjtNums in body_user + int nuser_jnt; // number of mjtNums in jnt_user + int nuser_geom; // number of mjtNums in geom_user + int nuser_site; // number of mjtNums in site_user + int nuser_cam; // number of mjtNums in cam_user + int nuser_tendon; // number of mjtNums in tendon_user + int nuser_actuator; // number of mjtNums in actuator_user + int nuser_sensor; // number of mjtNums in sensor_user + int nkey; // number of keyframes + int njmax; // (deprecated) max number of constraints + int nconmax; // (deprecated) max number of detected contacts + size_t nstack; // (deprecated) number of mjtNums in mjData stack // global data - mjString comment; // comment at top of XML - mjString modelfiledir; // path to model file + mjString comment; // comment at top of XML + mjString modelfiledir; // path to model file // other - bool hasImplicitPluginElem; // already encountered an implicit plugin sensor/actuator + bool hasImplicitPluginElem; // already encountered an implicit plugin sensor/actuator } mjSpec; @@ -148,7 +148,7 @@ typedef struct _mjsOrientation { // alternative orientation specifiers typedef struct _mjsPlugin { // plugin specification - mjElement* instance; // object type + mjElement* instance; // element type mjString name; // name mjString instance_name; // instance name int plugin_slot; // global registered slot number of the plugin @@ -158,7 +158,7 @@ typedef struct _mjsPlugin { // plugin specification typedef struct _mjsBody { // body specification - mjElement* element; // object type + mjElement* element; // element type mjString name; // name mjString childclass; // childclass name @@ -186,7 +186,7 @@ typedef struct _mjsBody { // body specification typedef struct _mjsFrame { // frame specification - mjElement* element; // object type + mjElement* element; // element type mjString name; // name mjString childclass; // childclass name double pos[3]; // position @@ -197,7 +197,7 @@ typedef struct _mjsFrame { // frame specification typedef struct _mjsJoint { // joint specification - mjElement* element; // object type + mjElement* element; // element type mjString name; // name mjString classname; // class name mjtJoint type; // joint type @@ -238,7 +238,7 @@ typedef struct _mjsJoint { // joint specification typedef struct _mjsGeom { // geom specification - mjElement* element; // object type + mjElement* element; // element type mjString name; // name mjString classname; // classname mjtGeom type; // geom type @@ -287,7 +287,7 @@ typedef struct _mjsGeom { // geom specification typedef struct _mjsSite { // site specification - mjElement* element; // object type + mjElement* element; // element type mjString name; // name mjString classname; // class name @@ -311,7 +311,7 @@ typedef struct _mjsSite { // site specification typedef struct _mjsCamera { // camera specification - mjElement* element; // object type + mjElement* element; // element type mjString name; // name mjString classname; // class name @@ -340,7 +340,7 @@ typedef struct _mjsCamera { // camera specification typedef struct _mjsLight { // light specification - mjElement* element; // object type + mjElement* element; // element type mjString name; // name mjString classname; // class name @@ -368,7 +368,7 @@ typedef struct _mjsLight { // light specification typedef struct _mjsFlex { - mjElement* element; // object type + mjElement* element; // element type mjString name; // name mjString classname; // class name @@ -409,7 +409,7 @@ typedef struct _mjsFlex { typedef struct _mjsMesh { // mesh specification - mjElement* element; // object type + mjElement* element; // element type mjString name; // name mjString classname; // class name mjString content_type; // content type of file @@ -430,7 +430,7 @@ typedef struct _mjsMesh { // mesh specification typedef struct _mjsHField { // height field specification - mjElement* element; // object type + mjElement* element; // element type mjString name; // name mjString content_type; // content type of file mjString file; // file: (nrow, ncol, [elevation data]) @@ -444,7 +444,7 @@ typedef struct _mjsHField { // height field specification typedef struct _mjsSkin { // skin specification - mjElement* element; // object type + mjElement* element; // element type mjString name; // name mjString classname; // class name mjString file; // skin file @@ -471,7 +471,7 @@ typedef struct _mjsSkin { // skin specification typedef struct _mjsTexture { // texture specification - mjElement* element; // object type + mjElement* element; // element type mjString name; // name mjString classname; // class name mjtTexture type; // texture type @@ -505,7 +505,7 @@ typedef struct _mjsTexture { // texture specification typedef struct _mjsMaterial { // material specification - mjElement* element; // object type + mjElement* element; // element type mjString name; // name mjString classname; // class name mjString texture; // name of texture (empty: none) @@ -521,7 +521,7 @@ typedef struct _mjsMaterial { // material specification typedef struct _mjsPair { - mjElement* element; // object type + mjElement* element; // element type mjString name; // name mjString classname; // class name mjString geomname1; // name of geom 1 @@ -540,7 +540,7 @@ typedef struct _mjsPair { typedef struct _mjsExclude { - mjElement* element; // object type + mjElement* element; // element type mjString name; // name mjString bodyname1; // name of geom 1 mjString bodyname2; // name of geom 2 @@ -549,7 +549,7 @@ typedef struct _mjsExclude { typedef struct _mjsEquality { // equality specification - mjElement* element; // object type + mjElement* element; // element type mjString name; // name mjString classname; // class name mjtEq type; // constraint type @@ -564,7 +564,7 @@ typedef struct _mjsEquality { // equality specification typedef struct _mjsTendon { // tendon specification - mjElement* element; // object type + mjElement* element; // element type mjString name; // name mjString classname; // class name @@ -596,13 +596,13 @@ typedef struct _mjsTendon { // tendon specification typedef struct _mjsWrap { // wrapping object specification - mjElement* element; // object type + mjElement* element; // element type mjString info; // message appended to errors } mjsWrap; typedef struct _mjsActuator { // actuator specification - mjElement* element; // object type + mjElement* element; // element type mjString name; // name mjString classname; // class name @@ -646,7 +646,7 @@ typedef struct _mjsActuator { // actuator specification typedef struct _mjsSensor { // sensor specification - mjElement* element; // object type + mjElement* element; // element type mjString name; // name mjString classname; // class name @@ -674,7 +674,7 @@ typedef struct _mjsSensor { // sensor specification typedef struct _mjsNumeric { // custom numeric field specification - mjElement* element; // object type + mjElement* element; // element type mjString name; // name mjDoubleVec data; // initialization data int size; // array size, can be bigger than data size @@ -683,7 +683,7 @@ typedef struct _mjsNumeric { // custom numeric field specification typedef struct _mjsText { // custom text specification - mjElement* element; // object type + mjElement* element; // element type mjString name; // name mjString data; // text string mjString info; // message appended to compiler errors @@ -691,7 +691,7 @@ typedef struct _mjsText { // custom text specification typedef struct _mjsTuple { // tuple specification - mjElement* element; // object type + mjElement* element; // element type mjString name; // name mjIntVec objtype; // object types mjStringVec objname; // object names @@ -701,7 +701,7 @@ typedef struct _mjsTuple { // tuple specification typedef struct _mjsKey { // keyframe specification - mjElement* element; // object type + mjElement* element; // element type mjString name; // name double time; // time mjDoubleVec qpos; // qpos @@ -716,7 +716,7 @@ typedef struct _mjsKey { // keyframe specification typedef struct _mjsDefault { // default specification mjString name; // name - mjElement* element; // object type + mjElement* element; // element type mjsJoint* joint; // joint defaults mjsGeom* geom; // geom defaults mjsSite* site; // site defaults @@ -732,38 +732,44 @@ typedef struct _mjsDefault { // default specification } mjsDefault; -//---------------------------------- API functions ------------------------------------------------- +//---------------------------------- Top-level spec manipulation ----------------------------------- -// Create model. +// Create spec. MJAPI mjSpec* mjs_createSpec(); -// Copy model. -MJAPI mjSpec* mjs_copySpec(const mjSpec* s); - -// Copy back model. -MJAPI void mjs_copyBack(mjSpec* s, const mjModel* m); - -// Compile model. +// Compile spec to model. MJAPI mjModel* mjs_compile(mjSpec* s, const mjVFS* vfs); -// Attach child body to a frame of the parent, return 0 if success +// Copy spec. +MJAPI mjSpec* mjs_copySpec(const mjSpec* s); + +// Get compiler error message from spec. +MJAPI const char* mjs_getError(mjSpec* s); + +// Return 1 if compiler error is a warning. +MJAPI int mjs_isWarning(mjSpec* s); + +// Copy model fields back into spec. +MJAPI void mjs_copyBack(mjSpec* s, const mjModel* m); + +// Delete spec. +MJAPI void mjs_deleteSpec(mjSpec* s); + + +//---------------------------------- Attachment ---------------------------------------------------- + +// Attach child body to a parent frame, return 0 on success. MJAPI int mjs_attachBody(mjsFrame* parent, const mjsBody* child, const char* prefix, const char* suffix); -// Attach child frame to a parent body, return 0 if success +// Attach child frame to a parent body, return 0 if success. MJAPI int mjs_attachFrame(mjsBody* parent, const mjsFrame* child, const char* prefix, const char* suffix); -// Get error message from model. -MJAPI const char* mjs_getError(mjSpec* s); -// Return 1 if model has warnings. -MJAPI int mjs_isWarning(mjSpec* s); +//---------------------------------- Add tree elements --------------------------------------------- -// Delete model. -MJAPI void mjs_deleteSpec(mjSpec* s); - -// Add child body to body, return child spec. +// Add child body to body, return child. MJAPI mjsBody* mjs_addBody(mjsBody* body, mjsDefault* def); // Add site to body, return site spec. @@ -787,34 +793,28 @@ MJAPI mjsLight* mjs_addLight(mjsBody* body, mjsDefault* def); // Add frame to body. MJAPI mjsFrame* mjs_addFrame(mjsBody* body, mjsFrame* parentframe); -// Add flex to model. + +//---------------------------------- Add non-tree elements ----------------------------------------- + +// Add actuator. +MJAPI mjsActuator* mjs_addActuator(mjSpec* s, mjsDefault* def); + +// Add sensor. +MJAPI mjsSensor* mjs_addSensor(mjSpec* s); + +// Add flex. MJAPI mjsFlex* mjs_addFlex(mjSpec* s); -// Add mesh to model. -MJAPI mjsMesh* mjs_addMesh(mjSpec* s, mjsDefault* def); - -// Add height field to model. -MJAPI mjsHField* mjs_addHField(mjSpec* s); - -// Add skin to model. -MJAPI mjsSkin* mjs_addSkin(mjSpec* s); - -// Add texture to model. -MJAPI mjsTexture* mjs_addTexture(mjSpec* s); - -// Add material to model. -MJAPI mjsMaterial* mjs_addMaterial(mjSpec* s, mjsDefault* def); - -// Add pair to model. +// Add contact pair. MJAPI mjsPair* mjs_addPair(mjSpec* s, mjsDefault* def); -// Add excluded body pair to model. +// Add excluded body pair. MJAPI mjsExclude* mjs_addExclude(mjSpec* s); -// Add equality to model. +// Add equality. MJAPI mjsEquality* mjs_addEquality(mjSpec* s, mjsDefault* def); -// Add tendon to model. +// Add tendon. MJAPI mjsTendon* mjs_addTendon(mjSpec* s, mjsDefault* def); // Wrap site using tendon. @@ -829,42 +829,48 @@ MJAPI mjsWrap* mjs_wrapJoint(mjsTendon* tendon, const char* name, double coef); // Wrap pulley using tendon. MJAPI mjsWrap* mjs_wrapPulley(mjsTendon* tendon, double divisor); -// Add actuator to model. -MJAPI mjsActuator* mjs_addActuator(mjSpec* s, mjsDefault* def); - -// Add sensor to model. -MJAPI mjsSensor* mjs_addSensor(mjSpec* s); - -// Add numeric to model. +// Add numeric. MJAPI mjsNumeric* mjs_addNumeric(mjSpec* s); -// Add text to model. +// Add text. MJAPI mjsText* mjs_addText(mjSpec* s); -// Add tuple to model. +// Add tuple. MJAPI mjsTuple* mjs_addTuple(mjSpec* s); -// Add keyframe to model. +// Add keyframe. MJAPI mjsKey* mjs_addKey(mjSpec* s); -// Add plugin to model. +// Add plugin. MJAPI mjsPlugin* mjs_addPlugin(mjSpec* s); -// Add default to model. +// Add default. MJAPI mjsDefault* mjs_addDefault(mjSpec* s, const char* classname, int parentid, int* id); -// Get model spec from body. + +//---------------------------------- Add assets ---------------------------------------------------- + +// Add mesh. +MJAPI mjsMesh* mjs_addMesh(mjSpec* s, mjsDefault* def); + +// Add height field. +MJAPI mjsHField* mjs_addHField(mjSpec* s); + +// Add skin. +MJAPI mjsSkin* mjs_addSkin(mjSpec* s); + +// Add texture. +MJAPI mjsTexture* mjs_addTexture(mjSpec* s); + +// Add material. +MJAPI mjsMaterial* mjs_addMaterial(mjSpec* s, mjsDefault* def); + + +//---------------------------------- Find/get utilities -------------------------------------------- + +// Get spec from body. MJAPI mjSpec* mjs_getSpec(mjsBody* body); -// Get default corresponding to an mjElement. -MJAPI mjsDefault* mjs_getDefault(mjElement* element); - -// Find default in model by class name. -MJAPI mjsDefault* mjs_findDefault(mjSpec* s, const char* classname); - -// Get global default from model. -MJAPI mjsDefault* mjs_getSpecDefault(mjSpec* s); - // Find body in model by name. MJAPI mjsBody* mjs_findBody(mjSpec* s, const char* name); @@ -877,9 +883,21 @@ MJAPI mjsMesh* mjs_findMesh(mjSpec* s, const char* name); // Find frame by name. MJAPI mjsFrame* mjs_findFrame(mjSpec* s, const char* name); +// Get default corresponding to an element. +MJAPI mjsDefault* mjs_getDefault(mjElement* element); + +// Find default in model by class name. +MJAPI mjsDefault* mjs_findDefault(mjSpec* s, const char* classname); + +// Get global default from model. +MJAPI mjsDefault* mjs_getSpecDefault(mjSpec* s); + // Get element id. MJAPI int mjs_getId(mjElement* element); + +//---------------------------------- Attribute setters --------------------------------------------- + // Copy text to string. MJAPI void mjs_setString(mjString dest, const char* text); @@ -907,33 +925,39 @@ MJAPI void mjs_appendFloatVec(mjFloatVecVec dest, const float* array, int size); // Copy double array to vector. MJAPI void mjs_setDouble(mjDoubleVec dest, const double* array, int size); +// Set plugin attributes. +MJAPI void mjs_setPluginAttributes(mjsPlugin* plugin, void* attributes); + + +//---------------------------------- Attribute getters --------------------------------------------- + // Get string contents. MJAPI const char* mjs_getString(mjString source); // Get double array contents and optionally its size. MJAPI const double* mjs_getDouble(mjDoubleVec source, int* size); -// Set plugin attributes. -MJAPI void mjs_setPluginAttributes(mjsPlugin* plugin, void* attributes); + +//---------------------------------- Other utilities ----------------------------------------------- // Set active plugins. MJAPI void mjs_setActivePlugins(mjSpec* s, void* activeplugins); -// Set default. +// Set element's default. MJAPI void mjs_setDefault(mjElement* element, mjsDefault* def); -// Set frame. +// Set element's enlcosing frame. MJAPI void mjs_setFrame(mjElement* dest, mjsFrame* frame); // Resolve alternative orientations to quat. MJAPI const char* mjs_resolveOrientation(double quat[4], mjtByte degree, const char* sequence, const mjsOrientation* orientation); -// Compute quat and inertia from body->fullinertia. +// Compute quat and inertia from fullinertia, return error if any. MJAPI const char* mjs_setFullInertia(mjsBody* body, double quat[4], double inertia[3]); -//---------------------------------- Initialization functions -------------------------------------- +//---------------------------------- Initialization ----------------------------------------------- // Default model attributes. MJAPI void mjs_defaultSpec(mjSpec& model); @@ -1010,7 +1034,8 @@ MJAPI void mjs_defaultKey(mjsKey& key); // Default plugin attributes. MJAPI void mjs_defaultPlugin(mjsPlugin& plugin); -//------------------------- Cache functions ------------------------------------ + +//---------------------------------- Compiler cache ------------------------------------------------ typedef struct _mjCache* mjCache;