00001 /* 00002 * PROPRIETARY INFORMATION. This software is proprietary to 00003 * Side Effects Software Inc., and is not to be reproduced, 00004 * transmitted, or disclosed in any way without written permission. 00005 * 00006 * Produced by: 00007 * Side Effects Software Inc 00008 * 123 Front Street West, Suite 1401 00009 * Toronto, Ontario 00010 * Canada M5J 2M2 00011 * 416-504-9876 00012 * 00013 * NAME: HDK_SOHO_API.h (Doxygen) 00014 * 00015 * COMMENTS: Doxygen doesn't process Python very well. This definition is 00016 * solely for documentation and should not be used for code. 00017 */ 00018 00019 #ifndef __HDK_SOHO_API__ 00020 #define __HDK_SOHO_API__ 00021 00022 namespace HDK_SOHO_API { 00023 /// @namespace HDK_SOHO_API 00024 /// @brief Documentation for SOHO API (<b>documentation only</b>) 00025 /// 00026 /// The SOHO API is currently only available through a Python API. The 00027 /// functions are documented in the help() of the soho module. However, 00028 /// this document provides documentation in a more usable form. 00029 /// 00030 /// @warning These functions do not exist in a C++ API 00031 00032 /// @brief Initialize the SOHO scene 00033 /// 00034 /// SOHO maintains an internal representation of the Houdini Scene. SOHO 00035 /// may filter some objects out of the render scene. It also flattens all 00036 /// instancing so that each instanced object is represented as a single 00037 /// SOHO object. This includes DOP instancing. 00038 /// 00039 /// The camera path may be NULL, in which case there will be no camera in 00040 /// the scene and the scene will be considered to be contained by "/obj". 00041 /// 00042 /// This function will also set the internal state by evaluating 00043 /// - @c soho_precision @n 00044 /// Output floating point precision, default := 12 00045 /// - @c soho_indentstep - Default := 4 00046 /// Indent step for indent() function 00047 /// - @c soho_almostzero - Default := 0 00048 /// Real numbers which have their value less than this tolerance 00049 /// will be output as 0 exactly. 00050 /// - @c soho_safename - Default := False 00051 /// Change object names to "safe" names. Safe names follow 00052 /// standard variable naming conventions, only alpha-numeric 00053 /// characters and the underscore ('_') 00054 /// - @c soho_autoheadlight - Default := True 00055 /// Automatically add a light at the camera's location if there are 00056 /// no lights in the scene. 00057 /// 00058 /// The method will fail if the user specifes a camera path, but there is 00059 /// no corresponding camera in the Houdini scene. 00060 /// 00061 /// When rendering from the viewport menu, this function will succeed even 00062 /// if the camera doesn't exist. See @ref HDK_SOHO_Overrides for details. 00063 /// 00064 /// The global indent level is reset to 0. 00065 bool initialize(fpreal render_time, const char *camera_path); 00066 00067 /// @brief Reset the SOHO scene 00068 /// 00069 /// This function will re-initialize the SOHO scene with an empty scene. 00070 /// The output driver object will be kept in the scene. 00071 /// @note This function is called automatically at the completion of the 00072 /// Python script. 00073 void finalize(); 00074 00075 /// @brief Add or remove objects from the SOHO scene 00076 /// 00077 /// @param render_time @n 00078 /// The time to be used for filtering evaluations 00079 /// @param geometry_pattern @n 00080 /// An object name pattern used to match geometry objects. Only 00081 /// objects which match the name pattern will be considered for the 00082 /// operation. 00083 /// @param light_pattern @n 00084 /// An object name pattern used to match light objects. 00085 /// @param fog_pattern @n 00086 /// An object name pattern used to match fog objects. 00087 /// @param parameter_filtering @n 00088 /// When selecting objects for addition to the scene, turning on 00089 /// parameter_filtering will cause parameter evaluation to before 00090 /// acceptance of an object. 00091 /// - For geometry objects: Evaluate the display flag & display channel 00092 /// - For fog objects: Evaluate the display flag & display channel 00093 /// - For light objects: Evaluate the "dimmer" channel. If 0, skip 00094 /// the light. 00095 /// @param remove_objects @n 00096 /// Remove selected objects from the scene (instead of adding to the 00097 /// scene) 00098 /// 00099 /// This function will expand all instance objects (including point 00100 /// instancing). 00101 /// 00102 /// <b> Sub-network Filtering </b> @n 00103 /// When evaluating a sub-network object which matches the candidate 00104 /// pattern, the @c subnet_filter parameter is evaluated on the 00105 /// sub-network. This parameter can have three possible values 00106 /// - @c all @n 00107 /// All children of the sub-network are included in the SOHO scene. 00108 /// - @c pattern @n 00109 /// The parameter @c subnet_pattern is evaluated and only children which 00110 /// match that pattern are selected. 00111 /// - @c display (default) @n 00112 /// Use the parameter_filtering criteria for object selection. 00113 /// 00114 /// @see lockCandidates() 00115 bool addCandidates(fpreal render_time, 00116 const char *geometry_pattern, 00117 const char *light_pattern, 00118 const char *fog_pattern, 00119 bool parameter_filtering = true, 00120 bool remove_objects = false); 00121 00122 /// Finalize the object selection made by addCandidates() 00123 void lockCandidates(); 00124 00125 /// @brief Get SOHO file descriptors 00126 /// 00127 /// The SOHO output driver evaluates the @c soho_outputmode parameter, and 00128 /// based on its value will create 2 internal file descriptors. 00129 /// @param descriptor @ 00130 /// - @c 1 will return the file descriptor tied to the output stream 00131 /// (i.e. the disk file specified by @c soho_diskfile or the pipe 00132 /// command specified by @c soho_pipecmd) 00133 /// - @c 2 will return the file descriptor tied to the error stream. 00134 /// Data written to this stream will be added to the output driver as 00135 /// an error message. 00136 /// Values other than 1 or 2 return NULL. 00137 FILE *getFile(int descriptor); 00138 00139 /// @brief Output indented text on the output stream 00140 /// 00141 /// This is a convenience function to indent the SOHO output stream. In 00142 /// Python code, this is equivalent to: @code 00143 /// def indent(bump=0, text="", comment="#', close_comment=""): 00144 /// global theIndent 00145 /// bump *= soho.getDefaultedInt("soho_indentstep", [4])[0] 00146 /// if bump < 0: 00147 /// theIndent += bump 00148 /// sys.stdout.write("%*s" % (theIndent, "")) 00149 /// if text: 00150 /// sys.stdout.write(text) 00151 /// if comment: 00152 /// if bump < 0: 00153 /// sys.stdout.write("\t %s } %s" % (comment, closecomment)) 00154 /// else: 00155 /// sys.stdout.write("\t %s { %s" % (comment, closecomment)) 00156 /// if bump > 0: 00157 /// theIndent += bump 00158 /// @endcode 00159 void indent(int bump=0, text="", comment="#", close_comment=""); 00160 00161 /// @brief Print an array to the output stream 00162 /// 00163 /// This is a convenience function to print an array of values to the SOHO 00164 /// output stream. In Python code, this is equivalent to: @code 00165 /// def printArray(prefix, value, suffix): 00166 /// precision = soho.getDefaultedInt("soho_precision", [12])[0] 00167 /// sys.stdout.write(prefix) 00168 /// for i in value: 00169 /// if type(i) == float: 00170 /// sys.stdout.write(' %.*g' % (prec, i)) 00171 /// else: 00172 /// sys.stdout.write(' %s' % repr(i)) 00173 /// sys.stdout.write(suffix) 00174 /// @endcode 00175 /// @see arrayToString() 00176 void printArray(const char *prefix, 00177 PyObject *list, 00178 const char *suffix); 00179 00180 /// @brief Print an array to a string object 00181 /// 00182 /// This is a convenience function to print an array of values to the SOHO 00183 /// output stream. In Python code, this is equivalent to: @code 00184 /// def arrayToString(prefix, value, suffix): 00185 /// precision = soho.getDefaultedInt("soho_precision", [12])[0] 00186 /// result = prefix 00187 /// for i in value: 00188 /// if type(i) == float: 00189 /// result += ' %.*g' % (prec, i) 00190 /// else: 00191 /// result += ' %s' % repr(i) 00192 /// result += suffix 00193 /// return result 00194 /// @endcode 00195 /// @see printArray() 00196 const char *arrayToString(const char *prefix, 00197 PyObject *list, 00198 const char *suffix); 00199 00200 /// @brief Store blind data on a SOHO object 00201 /// 00202 /// SOHO objects are referenced by handles in the Python API. There is a 00203 /// class wrapped around the integer handle, but multiple instances of the 00204 /// class may be created for the same object. SOHO provides a way to store 00205 /// blind data on the object. 00206 /// 00207 /// The data is stored in a dictionary. 00208 /// @see getObjectData(), clearObjectData() 00209 void storeObjectData(int handle, const char *name, void *data); 00210 00211 /// @brief Get blind data from a SOHO object 00212 /// 00213 /// SOHO objects are referenced by handles in the Python API. There is a 00214 /// class wrapped around the integer handle, but multiple instances of the 00215 /// class may be created for the same object. SOHO provides a way to store 00216 /// blind data on the object. 00217 /// 00218 /// The data is stored in a dictionary. 00219 /// @see storeObjectData(), clearObjectData() 00220 void *getObjectData(int handle, const char *name); 00221 00222 /// @brief Clear blind data from a SOHO object 00223 /// 00224 /// SOHO objects are referenced by handles in the Python API. There is a 00225 /// class wrapped around the integer handle, but multiple instances of the 00226 /// class may be created for the same object. SOHO provides a way to store 00227 /// blind data on the object. 00228 /// 00229 /// Multiple entries can be cleared from the dictionary at one time. 00230 /// 00231 /// The data is stored in a dictionary. 00232 /// @see storeObjectData(), getObjectData() 00233 void *clearObjectData(int handle, const char *name, ...); 00234 00235 /// @brief Evaluate parameters on an object 00236 /// 00237 /// The evaluate() function is the work-horse in SOHO. The function takes 00238 /// a Python @c list or @c dict of parameter objects and returns a @c list 00239 /// or @c dict of evaluated parameters. The parameter object should have 00240 /// the following attributes: 00241 /// - @c Key: A unique name for the parameter (used in the returned @c dict) 00242 /// - @c Houdini: The name of a Houdini parameter to evaluate 00243 /// - @c Type: The type of data expected (i.e. how the parameter should be 00244 /// evaluated). Possible values are: 'float', 'bool', 'int', 'string', 00245 /// 'shader', 'bounds', 'oplist'. 00246 /// - @c Default: Optional default value 00247 /// - @c SkipDefault: If the Houdini parameter is at it's default value, 00248 /// and this attribute is True, then, the parameter will not be returned 00249 /// in the resulting @c list or @c dict. 00250 /// 00251 /// There is a sample class object defined (SohoParm) in soho.py which is 00252 /// used throughout the factory Python scripts. 00253 /// 00254 /// After evaluation, the parameter object will have a new attribute 00255 /// @c Value which stores the resulting value. The @c Value attribute will 00256 /// always be a list/tuple, even if the parameter is a scalar. 00257 /// 00258 /// For example: @code 00259 /// def getDefaultedInt(object_handle, name, default_value): 00260 /// # Create a parameter list. Specify the default value to be 00261 /// # returned if the parameter cannot be evaluated. 00262 /// parmlist = [ SohoParm(name, 'int', default_value, False) ] 00263 /// # Evaluate the parameter list 00264 /// parmlist = evaluate(parmlist, None, object_handle) 00265 /// return parmlist[0].Value 00266 /// @endcode 00267 /// This could also be implemented as: @code 00268 /// def getDefaultedInt(object_handle, name, default_value): 00269 /// # Create a parameter list. Specify the default value to be 00270 /// # returned if the parameter cannot be evaluated. 00271 /// parmlist = [ SohoParm(name, 'int', [], True) ] 00272 /// # Evaluate the parameter list. If the evaluation fails, then 00273 /// # return the default_value. 00274 /// if not evaluate(parmlist, None, object_handle): 00275 /// return default_value 00276 /// return parmlist[0].Value 00277 /// @endcode 00278 /// 00279 /// @param parameters @n 00280 /// A Python @c list or @c dict of parameter objects 00281 /// @param time @n 00282 /// The evaluation time. If no evaluation time is specified, the 00283 /// time given by initialize() is used. 00284 /// @param handle @n 00285 /// An object handle identifier. This may be 0 to evaluate 00286 /// parameters on the output driver (i.e. global parameters). 00287 /// @return 00288 /// If parameters were evaluated, returns a @c list or @c dict of 00289 /// parameters with a @c Value attribute set to the evaluated 00290 /// results. Otherwise, returns @c None 00291 /// 00292 /// @note 00293 /// SOHO has @b intrinsic parameters. These @b intrinsic parameters are 00294 /// used to evaluate internal state of SOHO. It's possible to get a 00295 /// list of all tokens by evaluating "state:alltokens" or 00296 /// "state:allgeotokens" (to get geometry specific tokens). Some common 00297 /// tokens include: 00298 /// - @c state:alltokens @n 00299 /// A list of all intrinsic parameters known to SOHO 00300 /// - @c state:allgeotokens @n 00301 /// A list of all geometry intrinsic parameters known to SOHO 00302 /// - @c state:precision @n Floating point precision 00303 /// - @c state:houdiniversion @n The Houdini version string 00304 /// - @c state:time @n The time passed in initialize() 00305 /// - @c objlist:camera @n The list of camera objects 00306 /// - @c objlist:light @n The list of light objects 00307 /// - @c objlist:instance @n The list of instance/geometry objects 00308 /// - @c objlist:lightmask @n 00309 /// The lights affecting an object (includes category selections 00310 /// and bundle evaluations). 00311 /// - @c object:name @n The object name 00312 /// - @c object:soppath @n The object's render SOP 00313 /// - @c object:creator @n The object's creator object 00314 /// - @c space:world @n The object's world space 00315 /// - @c space:local @n The object's local space 00316 /// 00317 PyObject *evaluate(PyObject *parameters, fpreal time, int handle); 00318 00319 /// @brief Process a shader, evaluating VOP or op: references 00320 /// 00321 /// When a shader is defined by a VOP network, the VOP network may need to 00322 /// be processed for a valid shader to exist. 00323 /// 00324 /// In addition, some shaders may have arguments which reference other 00325 /// assets in the .hip file (i.e. COP images). This function will also 00326 /// process arguments, scanning for 'op:' or 'opdef:' to determine whether 00327 /// assets have to be passed to the render script. 00328 /// 00329 /// At the current time, scanning for @c op: is mantra/IFD specific. 00330 /// 00331 /// @return 00332 /// The function returns two strings. 00333 /// - result[0] @n 00334 /// The first string in the array returned is the mangled shader string. 00335 /// This may have the shader name changed (if the shader was defined by 00336 /// VOPs) or have parameter values changed (if they referred to COPs). 00337 /// - result[1] @n 00338 /// The second string contains data needed by rendering. This may 00339 /// contain compiled .vex object code for IFD, or other data depending on 00340 /// the rendering style set by the output driver (See @ref HDK_SOHO_ROP) 00341 /// 00342 /// @param shader_string @n 00343 /// The shader string to process 00344 /// @param force_vop_compilation @n 00345 /// SOHO will output inline .vex code if it believes that mantra will not 00346 /// be able to load the shader code independently. This will happen if 00347 /// the VEX code is generated by an embedded VOP network for example. 00348 /// However, if Houdini believes that mantra will be able to load the VEX 00349 /// code from an OTL, it will skip inlining the VEX code. This option 00350 /// tells processShader() to forcibly embed VEX code regardless of what 00351 /// Houdini believes. 00352 /// @param force_cop_embedding @n 00353 /// SOHO will embed an image defined by a COP if it believes that mantra 00354 /// will not be able to load the image independently. If Houdini 00355 /// believes that mantra will be able to load the image (i.e. from an 00356 /// OTL), it will skip embedding the COP image in the IFD. 00357 /// This option tells processShader() to forcibly embed image regardless 00358 /// of what Houdini believes. 00359 /// 00360 /// @note 00361 /// processShader will also scan for CVEX shader references and process 00362 /// these arguments if needed. 00363 UT_StringArray processShader(const char *shader_string, 00364 bool force_vop_compilation = false, 00365 bool force_cop_embedding = false); 00366 00367 /// @brief Push a set of parameter overrides 00368 /// 00369 /// This function takes a dictionary of name/value pairs. When SOHO is 00370 /// asked to evaluate a parameter, it first checks to see whether the 00371 /// parameter is defined in the current overrides. If so, the value from 00372 /// the overrides is returned. 00373 /// 00374 /// The overrides form a stack, and @b all pushed overrides are scanned 00375 /// when parameters are evaluated. 00376 /// 00377 /// pushOverrides() and popOverrides() are wrapped in the PropertyOverride 00378 /// object (soho.py). 00379 /// 00380 /// @note 00381 /// At the current time, only values which can be represented in a 00382 /// UT_Options object are processed properly. 00383 /// @see popOverrides() 00384 void pushOverrides(const UT_Options &options); 00385 00386 /// Pop the override stack (see pushOverrides()); 00387 void popOverrides(); 00388 00389 /// @brief Start iterating over a list of objects 00390 /// 00391 /// Create an iterator object which allows iteration over a selection of 00392 /// objects in the SOHO scene. 00393 /// 00394 /// @param type @n 00395 /// The type of iteration. This should be one of: 00396 /// - @c objlist:all - All objects in the scene 00397 /// - @c objlist:outputdriver - All output drivers (typically one) 00398 /// - @c objlist:camera - All cameras in the scene 00399 /// - @c objlist:light - All light objects in the scene 00400 /// - @c objlist:instance - All instance/geometry objects in the scene 00401 /// - @c objlist:fog - All fog objects in the scene 00402 /// - @c objlist:space - All transform space objects (null objects) in the scene 00403 /// - @c objlist:shop - All SHOP's referenced by objects in the scene 00404 /// - @c objlist:deletedlight - All lights deleted (IPR mode) 00405 /// - @c objlist:deletedinstance - All instance/geometry objects deleted (IPR mode) 00406 /// - @c objlist:deletedfog - All fog objects deleted (IPR mode) 00407 /// - @c objlist:dirtylight - All light objects changed (IPR mode) 00408 /// - @c objlist:dirtyinstance - All instance objects changed (IPR mode) 00409 /// - @c objlist:dirtyfog - All fog objects changed (IPR mode) 00410 /// - @c objlist:dirtyspace - All space objects changed (IPR mode) 00411 /// - @c objlist:lightmask - Lights affecting an object 00412 /// - @c objlist:shadowmask - Instance/Geometry objects blocking light from a light source 00413 /// - @c objlist:reflectmask - Instance/Geometry objects visible in reflections from an object 00414 /// - @c objlist:refractmask - Instance/Geometry objects visible in refractions from an object 00415 /// - @c objlist:unlightmask - Lights not affecting an object 00416 /// - @c objlist:unshadowmask - Complement of objlist:shadowmask 00417 /// - @c objlist:unreflectmask - Complement of objlist:reflectmask 00418 /// - @c objlist:unrefractmask - Complement of objlist:refractmask 00419 /// @param time 00420 /// Evaluation time to evaluate the parameters controlling the selection 00421 /// @param object_handle 00422 /// The lightmask, shadowmask, reflectmask, refractmask can all be 00423 /// evaluated on a per-object basis. The handle can be -1 to evaluate 00424 /// the parameters on the output driver (for example for 'objlist:light') 00425 /// @param pattern_override 00426 /// Specify a pattern which filters objects based on object name. This 00427 /// defaults to "*". 00428 /// @param category_override 00429 /// Specify a pattern which filters objects based on category 00430 /// tags/selection tags. This defaults to "*". 00431 /// @see nextIterator() 00432 PyObject *newIterator(const char *type, 00433 fpreal time, 00434 int object_handle, 00435 const char *pattern_override, 00436 const char *category_override); 00437 00438 /// @brief Proceed to the next iteration of an iterator 00439 /// 00440 /// @param iterator An iterator created by newIterator() 00441 /// 00442 /// Iterates over the SOHO objects in the iterator, returning the object 00443 /// handle for the current object. An invalid handle (-1) is returned when 00444 /// the iteration is complete. 00445 /// 00446 /// For example, to implement an iteration over all light sources in a SOHO 00447 /// scene as a Python generator: @code 00448 /// def allLights(): 00449 /// it = newIterator('objlist:light', None, None, None,None) 00450 /// while True: 00451 /// handle = nextIterator(it) 00452 /// if result < 0: 00453 /// break 00454 /// yield handle 00455 /// @endcode 00456 /// 00457 int nextIterator(PyObject *iterator); 00458 00459 // --------------------------------------------------------------- 00460 // Geometry Methods 00461 // --------------------------------------------------------------- 00462 00463 /// @brief Create a geometry object 00464 /// 00465 /// @param path @n 00466 /// The Houdini path to a SOP object. This SOP's geometry will be 00467 /// evaluated. You can find the SOP path for an object by evaluating 00468 /// @code 00469 /// path = obj.getDefaultedString('object:soppath', time, [''])[0] 00470 /// geo_handle = gCreate(path, time) 00471 /// if geo_handle < 0: 00472 /// print 'Error getting geometry:', path 00473 /// @endcode 00474 /// @param cook_time 00475 /// The time used to evaluate the SOP's geometry 00476 /// @return 00477 /// The function returns an integer handle which can be used to reference 00478 /// the geometry. Handles less than 0 indicate errors evaluating the 00479 /// geometry. 00480 /// @note 00481 /// This is wrapped in the SohoGeometry class (sohog.py) 00482 /// @warning 00483 /// It is important to release the geometry with gDelete() 00484 int gCreate(const char *path, fpreal cook_time); 00485 00486 /// @brief Release a geometry handle 00487 /// 00488 /// Release the geometry associated with the handle. The handle should 00489 /// have been created with gCreate(). 00490 /// @note 00491 /// This is wrapped in the SohoGeometry class (sohog.py) 00492 void gDelete(int geo_handle); 00493 00494 /// @brief Partition geometry into new geometry objects 00495 /// 00496 /// Partitioning geometry splits one geometry object into a dictionary of 00497 /// geometry objects. Each element of the dictionary is composed of a 00498 /// sub-set of the primitives of the original geometry. The dictionary 00499 /// values are the handles associated with the geometry objects. You must 00500 /// call gDelete() on these handles. 00501 /// 00502 /// There are four styles of partitioning currently implemented. 00503 /// 00504 /// @b geo:partgroup @n 00505 /// In this case, the @c option parameter refers to a primitive group name. 00506 /// All primitives in that group are returned in a new geometry object. 00507 /// 00508 /// @b geo:partattrib @n 00509 /// In this case, the @c option parameter refers to a @b string attribute. 00510 /// The geometry is partitioned based on the values of the string. That 00511 /// is, all primitives which have the same string value are put into a 00512 /// single partition group. This approach can be used to partition 00513 /// geometry based on material assignments for example. 00514 /// 00515 /// @b geo:partlist @n 00516 /// This is the most flexible partitioning process. The @c option 00517 /// parameter in this case, refers to a list of strings. There should be 00518 /// one string for each primitive in the geometry. Each primitive will be 00519 /// placed in a partition named by the corresponding string. Python 00520 /// generator objects are accepted in this function. 00521 /// 00522 /// @b geo:partenlarge @n 00523 /// This is a special case partitioner which looks at edge connectedness of 00524 /// polygon sets. The @c option is ignored. The returned partition will 00525 /// contain a super-set of the original geometry which has additional 00526 /// polygons which were connected to the original geometry. This assumes 00527 /// that the geometry was part of a partitioned set. 00528 /// 00529 /// @b Examples @code 00530 /// # Create a single partition with all the primitives in the 00531 /// # group named 'renderme' 00532 /// partition('geo:partgroup', 'renderme') 00533 /// 00534 /// # Partition the geometry into partitions based on the value of 00535 /// # the 'material' attribute. 00536 /// partition('geo:partattrib', 'material') 00537 /// 00538 /// # Partition the geometry into partitions based on a generator 00539 /// def generator(nprimitives): 00540 /// for x in xrange(0, nprimitives): 00541 /// if isprime(x): 00542 /// return 'prime' 00543 /// else: 00544 /// return 'composite' 00545 /// partition('geo:partlist', generator(nprimitives)) 00546 /// @endcode 00547 /// 00548 /// @note 00549 /// This is wrapped in the SohoGeometry class (sohog.py) 00550 PyDictObject *gPartition(int geo_handle, const char *style, 00551 PyObject *option); 00552 00553 /// @brief Tesselate geometry into polygons (Houdini 10.5 and greater) 00554 /// 00555 /// This takes source geometry and creates a tesselated version of the 00556 /// geometry. The tesselation is controlled using the options passed. 00557 /// For a current list of options, please see $HH/soho/soho.doc. However, 00558 /// some common options include: 00559 /// - tess:style @n 00560 /// Conversion style for geometry. The style should be one of 'lod' 00561 /// (tesselate based on level of detail) or 'div' (tesselate based on 00562 /// divisions). The default is 'lod' 00563 /// - tess:polysides @n 00564 /// The value should be an integer specifying the maximum number of sides 00565 /// of polygons. No polygon splitting will be performed if the value is 00566 /// less than 0. All polygons split will be guaranteed to be convex. 00567 /// Example: @code 00568 /// geo1 = gCreate(path); 00569 /// geo2 = tesselate(geo1, {'tess:style':'lod', 'tess:polysides':3}) 00570 /// @endcode 00571 int gTesselate(int geo_handle, UT_Options &options); 00572 00573 /// @brief Look up a geometry attribute 00574 /// 00575 /// Attributes in SOHO are accessed using integer handles. Valid handles 00576 /// have values greater than 0. The gAttribute() function will query 00577 /// geometry to find a handle to the named attribute. This handle can then 00578 /// be used by gValue() or gVertex() to evaluate the value from the 00579 /// geometry. 00580 /// 00581 /// SOHO maintains a list of @b intrinsic attributes which can be used to 00582 /// access information about the topology of the geometry, primitive 00583 /// properties or other intrinsic attributes which aren't tied directly to 00584 /// a user attribute. You can get a list of all geometry tokens using the 00585 /// evaluate() function (with the 'state:allgeotokens' parameter name). 00586 /// 00587 /// When the parameter owner is "geo:attrib", the attribute handle can be 00588 /// used to query information about attribute handles. The following 00589 /// intrinsic attributes are supported in this case: 00590 /// - 'geo:storage' @n 00591 /// Evaluate the storage type of the attribute (returns 'int', 'float' or 00592 /// 'string') 00593 /// - 'geo:vectorsize' @n 00594 /// Evaluate the tuple size of the attribute. 00595 /// - 'geo:allstrings' @n 00596 /// Return a list of all the unique strings associated with the 00597 /// attribute. This may return strings which aren't actually referenced 00598 /// in the geometry, but are stored on the attribute. 00599 /// 00600 /// Example: @code 00601 /// # Find the P point attribute and print it for the first 10 00602 /// # points 00603 /// P = gAttribute(geo_handle, 'geo:point', 'P') 00604 /// for i in range(10): 00605 /// print i, gValue(geo_handle, P, i) 00606 /// 00607 /// # Find the "intrinsic" attribute for the primitive type name 00608 /// # and print it out for the first 10 primitives 00609 /// pname = gAttribute(geo_handle, 'geo:primitive', 'geo:primname') 00610 /// for i in range(10): 00611 /// print i, gValue(geo_handle, pname, i) 00612 /// 00613 /// # Find an attribute to query the vector size of an attribute 00614 /// # Use this attribute to print out the vector size of the P and 00615 /// # pname attributes. 00616 /// a_vsize = gAttribute(geo_handle, 'geo:attrib', 'geo:vectorsize) 00617 /// P_size = gValue(geo_handle, a_vsize, P) 00618 /// primname_size = gValue(geo_handle, a_vsize, pname) 00619 /// print 'P[%d] pname[%d]' % (P_size, primname_size) 00620 /// @endcode 00621 /// 00622 /// @param geo_handle @n The geometry handle created with gCreate() 00623 /// @param owner @n 00624 /// The owner of the attribute. This may be one of 00625 /// - @c 'geo:point' @n 00626 /// A point attribute 00627 /// - @c 'geo:prim' @n 00628 /// A primitive attribute 00629 /// - @c 'geo:vertex' @n 00630 /// A vertex attribute 00631 /// - @c 'geo:global' @n 00632 /// A global (or detail) attribute 00633 /// - @c 'geo:attrib' @n 00634 /// An attribute of an attribute. Only supports intrinsic 00635 /// attributes. 00636 /// - @c 'geo:meta' @n 00637 /// An attribute used to query the metaball expression associated 00638 /// with the geometry. 00639 /// 00640 /// @param name @n 00641 /// The name of the attribute to look up. This may be the name of an @b 00642 /// intrinsic attribute. 00643 int gAttribute(int geo_handle, const char *owner, 00644 const char *name); 00645 00646 /// @brief Evaluate a geometry attribute 00647 /// 00648 /// @param geo_handle @n The geometry handle created by gCreate() 00649 /// @param attribute @n The attribute handle created by gAttribute() 00650 /// @param element @n 00651 /// The number of the element to be evaluated. This integer is dependent 00652 /// on the attribute type, and it's the users responsibility to ensure that 00653 /// the value has the correct meaning. The meaning is based on the 00654 /// attribute owner type: 00655 /// - @c 'geo:point' @n @c element refers to the point number 00656 /// - @c 'geo:prim' @n @c element refers to the primitive number 00657 /// - @c 'geo:global' @n @c element is ignored. 00658 /// - @c 'geo:attrib' @n @c element is the attribute handle to query 00659 /// - @c 'geo:vertex' @n 00660 /// @c element is a tuple of integers <tt>(primitive, vertex)</tt>. This 00661 /// uniquely identifies a vertex for evaluation. 00662 /// - @c 'geo:meta' @n 00663 /// @c element is the metaball expression (or sub-expression). 0 refers 00664 /// to the root expression. 00665 /// @return 00666 /// This function always returns a @b list of values. Even if the 00667 /// parameter is a scalar. This can lead to very subtle errors. For 00668 /// example, in the following code, nprims is a list object (not an 00669 /// int): @code 00670 /// nprim_handle = gAttribute(geo, 'geo:global', 'geo:primcount') 00671 /// nprims = gValue(geo, nprim_handle, 0) 00672 /// # Should be: vvv 00673 /// # nprims = gValue(geo, nprim_handle, 0)[0] 00674 /// # ^^^ 00675 /// @endcode 00676 PyListObject *gValue(int geo_handle, int attribute, int element); 00677 00678 /// @brief Evaluate a geometry attribute by (primitive,vertex) 00679 /// 00680 /// @param geo_handle @n The geometry handle created by gCreate() 00681 /// @param attribute @n The attribute handle created by gAttribute() 00682 /// @param primitive @n 00683 /// The primitive number for evaluation. 00684 /// @param vertex @n 00685 /// The vertex number for evaluation 00686 /// 00687 /// This function is equivalent to: @code 00688 /// gValue(geo_handle, attribute, (primitive, vertex)) 00689 /// @endcode 00690 /// @return 00691 /// This function always returns a @b list of values. Even if the 00692 /// parameter is a scalar. See gValue() 00693 PyListObject *gVertex(int geo_handle, int attribute, 00694 int primitive, int vertex); 00695 00696 /// @brief A short-cut to save geometry to a known format 00697 /// 00698 /// This method will call GU_Detail::save() to save the geometry to the 00699 /// given filename. If the filename is 'stdout.geo', 'stdout.bgeo' or 00700 /// 'stdout', the geometry will be saved to the SOHO output stream (as 00701 /// returned by getFile(1)) 00702 /// 00703 /// The options are passed to the GU_Detail::save() method and can be used 00704 /// to "tune" saving. Some common options include: 00705 /// - bool savegroups 00706 /// - bool savepointgroups 00707 /// - bool savepprimitivegroups 00708 /// 00709 /// @warning @b All the geometry from the root geometry is saved, even if 00710 /// the geometry is the result of a gPartition() call. This behaviour may 00711 /// change in the future, and so it should not be relied upon. 00712 bool gSaveAll(int geo_handle, const char *filename, 00713 const UT_Options &options); 00714 } 00715 00716 #endif
1.5.9