Houdini Engine 3.5
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
HAPI.h
Go to the documentation of this file.
1 /*
2  * PROPRIETARY INFORMATION. This software is proprietary to
3  * Side Effects Software Inc., and is not to be reproduced,
4  * transmitted, or disclosed in any way without written permission.
5  *
6  * COMMENTS:
7  * For parsing help, there is a variable naming convention we maintain:
8  * strings: char * and does not end in "buffer"
9  * binary: char * and is either exactly "buffer" or ends
10  * with "_buffer"
11  * single values: don't end with "_array" or "_buffer"
12  * arrays: <type> * and is either "array" or ends
13  * with "_array". Use "_fixed_array" to skip resize using
14  * tupleSize for the thrift generator.
15  * array length: is either "length", "count", or ends with
16  * "_length" or "_count". Use "_fixed_array" to skip resize
17  * using tupleSize for the thrift generator.
18  */
19 
20 #ifndef __HAPI_h__
21 #define __HAPI_h__
22 
23 #include "HAPI_API.h"
24 #include "HAPI_Common.h"
25 #include "HAPI_Helpers.h"
26 
27 /// @defgroup Sessions
28 /// Functions for creating and inspecting HAPI session state.
29 
30 /// @brief Creates a new in-process session. There can only be
31 /// one such session per host process.
32 ///
33 /// @ingroup Sessions
34 ///
35 /// @param[out] session
36 /// A ::HAPI_Session struct to receive the session id,
37 /// in this case always 0.
38 ///
40 
41 /// @brief Starts a Thrift RPC server process on the local host serving
42 /// clients on a TCP socket and waits for it to start serving.
43 /// It is safe to create an RPC session on local host using the
44 /// specified port after this call succeeds.
45 ///
46 /// @ingroup Sessions
47 /// @param[in] options
48 /// Options to configure the server being started.
49 ///
50 /// @param[in] port
51 /// The TCP socket to create on the server.
52 ///
53 /// @param[out] process_id
54 /// The process id of the server, if started successfully.
55 ///
57  const HAPI_ThriftServerOptions * options,
58  int port,
59  HAPI_ProcessId * process_id );
60 
61 /// @brief Creates a Thrift RPC session using a TCP socket as transport.
62 ///
63 /// @ingroup Sessions
64 /// @param[out] session
65 /// A ::HAPI_Session struct to receive the unique session id
66 /// of the new session.
67 ///
68 /// @param[in] host_name
69 /// The name of the server host.
70 ///
71 /// @param[in] port
72 /// The server port to connect to.
73 ///
75  const char * host_name,
76  int port );
77 
78 /// @brief Starts a Thrift RPC server process on the local host serving
79 /// clients on a Windows named pipe or a Unix domain socket and
80 /// waits for it to start serving. It is safe to create an RPC
81 /// session using the specified pipe or socket after this call
82 /// succeeds.
83 ///
84 /// @ingroup Sessions
85 ///
86 /// @param[in] options
87 /// Options to configure the server being started.
88 ///
89 /// @param[in] pipe_name
90 /// The name of the pipe or socket.
91 ///
92 /// @param[out] process_id
93 /// The process id of the server, if started successfully.
94 ///
96  const HAPI_ThriftServerOptions * options,
97  const char * pipe_name,
98  HAPI_ProcessId * process_id );
99 
100 /// @brief Creates a Thrift RPC session using a Windows named pipe
101 /// or a Unix domain socket as transport.
102 ///
103 /// @ingroup Sessions
104 ///
105 /// @param[out] session
106 /// A ::HAPI_Session struct to receive the unique session id
107 /// of the new session.
108 ///
109 /// @param[in] pipe_name
110 /// The name of the pipe or socket.
111 ///
113  const char * pipe_name );
114 
115 /// @brief Binds a new implementation DLL to one of the custom session
116 /// slots.
117 ///
118 /// @ingroup Sessions
119 ///
120 /// @param[in] session_type
121 /// Which custom implementation slot to bind the
122 /// DLL to. Must be one of ::HAPI_SESSION_CUSTOM1,
123 /// ::HAPI_SESSION_CUSTOM2, or ::HAPI_SESSION_CUSTOM3.
124 ///
125 /// @param[in] dll_path
126 /// The path to the custom implementation DLL.
127 ///
129  const char * dll_path );
130 
131 /// @brief Creates a new session using a custom implementation.
132 /// Note that the implementation DLL must already have
133 /// been bound to the session via calling
134 /// ::HAPI_BindCustomImplementation().
135 ///
136 /// @ingroup Sessions
137 ///
138 /// @param[in] session_type
139 /// session_type indicates which custom session
140 /// slot to create the session on.
141 ///
142 /// @param[in,out] session_info
143 /// Any data required by the custom implementation to
144 /// create its session.
145 ///
146 /// @param[out] session
147 /// A ::HAPI_Session struct to receive the session id,
148 /// The sessionType parameter of the struct should
149 /// also match the session_type parameter passed in.
150 ///
152  void * session_info,
153  HAPI_Session * session );
154 
155 /// @brief Checks whether the session identified by ::HAPI_Session::id is
156 /// a valid session opened in the implementation identified by
157 /// ::HAPI_Session::type.
158 ///
159 /// @ingroup Sessions
160 ///
161 /// @param[in] session
162 /// The ::HAPI_Session to check.
163 ///
164 /// @return ::HAPI_RESULT_SUCCESS if the session is valid.
165 /// Otherwise, the session is invalid and passing it to
166 /// other HAPI calls may result in undefined behavior.
167 ///
168 HAPI_DECL HAPI_IsSessionValid( const HAPI_Session * session );
169 
170 /// @brief Closes a session. If the session has been established using
171 /// RPC, then the RPC connection is closed.
172 ///
173 /// @ingroup Sessions
174 ///
175 /// @param[in] session
176 /// The HAPI_Session to close. After this call, this
177 /// session is invalid and passing it to HAPI calls other
178 /// than ::HAPI_IsSessionValid() may result in undefined
179 /// behavior.
180 ///
181 HAPI_DECL HAPI_CloseSession( const HAPI_Session * session );
182 
183 // INITIALIZATION / CLEANUP -------------------------------------------------
184 
185 /// @brief Check whether the runtime has been initialized yet using
186 /// ::HAPI_Initialize(). Function will return ::HAPI_RESULT_SUCCESS
187 /// if the runtime has been initialized and ::HAPI_RESULT_NOT_INITIALIZED
188 /// otherwise.
189 ///
190 /// @ingroup Sessions
191 ///
192 /// @param[in] session
193 /// The session of Houdini you are interacting with.
194 /// See @ref HAPI_Sessions for more on sessions.
195 /// Pass NULL to just use the default in-process session.
196 /// <!-- default NULL -->
197 ///
198 HAPI_DECL HAPI_IsInitialized( const HAPI_Session * session );
199 
200 /// @brief Create the asset manager, set up environment variables, and
201 /// initialize the main Houdini scene. No license check is done
202 /// during this step. Only when you try to load an asset library
203 /// (OTL) do we actually check for licenses.
204 ///
205 /// @ingroup Sessions
206 ///
207 /// @param[in] session
208 /// The session of Houdini you are interacting with.
209 /// See @ref HAPI_Sessions for more on sessions.
210 /// Pass NULL to just use the default in-process session.
211 /// <!-- default NULL -->
212 ///
213 /// @param[in] cook_options
214 /// Global cook options used by subsequent default cooks.
215 /// This can be overwritten by individual cooks but if
216 /// you choose to instantiate assets with cook_on_load
217 /// set to true then these cook options will be used.
218 ///
219 /// @param[in] use_cooking_thread
220 /// Use a separate thread for cooking of assets. This
221 /// allows for asynchronous cooking and larger stack size.
222 /// <!-- default true -->
223 ///
224 /// @param[in] cooking_thread_stack_size
225 /// Set the stack size of the cooking thread. Use -1 to
226 /// set the stack size to the Houdini default. This
227 /// value is in bytes.
228 /// <!-- default -1 -->
229 ///
230 /// @param[in] houdini_environment_files
231 /// A list of paths, separated by a ";" on Windows and a ":"
232 /// on Linux and Mac, to .env files that follow the same
233 /// syntax as the houdini.env file in Houdini's user prefs
234 /// folder. These will be applied after the default
235 /// houdini.env file and will overwrite the process'
236 /// environment variable values. You an use this to enforce
237 /// a stricter environment when running engine.
238 /// For more info, see:
239 /// http://www.sidefx.com/docs/houdini/basics/config_env
240 /// <!-- default NULL -->
241 ///
242 /// @param[in] otl_search_path
243 /// The directory where OTLs are searched for. You can
244 /// pass NULL here which will only use the default
245 /// Houdini OTL search paths. You can also pass in
246 /// multiple paths separated by a ";" on Windows and a ":"
247 /// on Linux and Mac. If something other than NULL is
248 /// passed the default Houdini search paths will be
249 /// appended to the end of the path string.
250 /// <!-- default NULL -->
251 ///
252 /// @param[in] dso_search_path
253 /// The directory where generic DSOs (custom plugins) are
254 /// searched for. You can pass NULL here which will
255 /// only use the default Houdini DSO search paths. You
256 /// can also pass in multiple paths separated by a ";"
257 /// on Windows and a ":" on Linux and Mac. If something
258 /// other than NULL is passed the default Houdini search
259 /// paths will be appended to the end of the path string.
260 /// <!-- default NULL -->
261 ///
262 /// @param[in] image_dso_search_path
263 /// The directory where image DSOs (custom plugins) are
264 /// searched for. You can pass NULL here which will
265 /// only use the default Houdini DSO search paths. You
266 /// can also pass in multiple paths separated by a ";"
267 /// on Windows and a ":" on Linux and Mac. If something
268 /// other than NULL is passed the default Houdini search
269 /// paths will be appended to the end of the path string.
270 /// <!-- default NULL -->
271 ///
272 /// @param[in] audio_dso_search_path
273 /// The directory where audio DSOs (custom plugins) are
274 /// searched for. You can pass NULL here which will
275 /// only use the default Houdini DSO search paths. You
276 /// can also pass in multiple paths separated by a ";"
277 /// on Windows and a ":" on Linux and Mac. If something
278 /// other than NULL is passed the default Houdini search
279 /// paths will be appended to the end of the path string.
280 /// <!-- default NULL -->
281 ///
282 HAPI_DECL HAPI_Initialize( const HAPI_Session * session,
283  const HAPI_CookOptions * cook_options,
284  HAPI_Bool use_cooking_thread,
285  int cooking_thread_stack_size,
286  const char * houdini_environment_files,
287  const char * otl_search_path,
288  const char * dso_search_path,
289  const char * image_dso_search_path,
290  const char * audio_dso_search_path );
291 
292 /// @brief Clean up memory. This will unload all assets and you will
293 /// need to call ::HAPI_Initialize() again to be able to use any
294 /// HAPI methods again.
295 ///
296 /// @note This does not release any licenses. The license will be returned when
297 /// the process terminates.
298 ///
299 /// @ingroup Sessions
300 ///
301 /// @param[in] session
302 /// The session of Houdini you are interacting with.
303 /// See @ref HAPI_Sessions for more on sessions.
304 /// Pass NULL to just use the default in-process session.
305 /// <!-- default NULL -->
306 ///
307 HAPI_DECL HAPI_Cleanup( const HAPI_Session * session );
308 
309 /// @defgroup Environment
310 /// Functions for reading and writing to the session environment
311 
312 /// @brief Gives back a certain environment integers like version number.
313 /// Note that you do not need a session for this. These constants
314 /// are hard-coded in all HAPI implementations, including HARC and
315 /// HAPIL. This should be the first API you call to determine if
316 /// any future API calls will mismatch implementation.
317 ///
318 /// @ingroup Environment
319 ///
320 /// @param[in] int_type
321 /// One of ::HAPI_EnvIntType.
322 ///
323 /// @param[out] value
324 /// Int value.
325 ///
326 HAPI_DECL HAPI_GetEnvInt( HAPI_EnvIntType int_type, int * value );
327 
328 /// @brief Gives back a certain session-specific environment integers
329 /// like current license type being used.
330 ///
331 /// @ingroup Environment
332 ///
333 /// @param[in] session
334 /// The session of Houdini you are interacting with.
335 /// See @ref HAPI_Sessions for more on sessions.
336 /// Pass NULL to just use the default in-process session.
337 /// <!-- default NULL -->
338 ///
339 /// @param[in] int_type
340 /// One of ::HAPI_SessionEnvIntType.
341 ///
342 /// @param[out] value
343 /// Int value.
344 ///
346  HAPI_SessionEnvIntType int_type,
347  int * value );
348 
349 /// @brief Get environment variable from the server process as an integer.
350 ///
351 /// @ingroup Environment
352 ///
353 /// @param[in] session
354 /// The session of Houdini you are interacting with.
355 /// See @ref HAPI_Sessions for more on sessions.
356 /// Pass NULL to just use the default in-process session.
357 /// <!-- default NULL -->
358 ///
359 /// @param[in] variable_name
360 /// Name of the environmnet variable.
361 ///
362 /// @param[out] value
363 /// The int pointer to return the value in.
364 ///
366  const char * variable_name,
367  int * value );
368 
369 /// @brief Get environment variable from the server process as a string.
370 ///
371 /// @ingroup Environment
372 ///
373 /// @param[in] session
374 /// The session of Houdini you are interacting with.
375 /// See @ref HAPI_Sessions for more on sessions.
376 /// Pass NULL to just use the default in-process session.
377 /// <!-- default NULL -->
378 ///
379 /// @param[in] variable_name
380 /// Name of the environmnet variable.
381 ///
382 /// @param[out] value
383 /// The HAPI_StringHandle pointer to return the value in.
384 ///
386  const char * variable_name,
387  HAPI_StringHandle * value );
388 
389 /// @brief Provides the number of environment variables that are in
390 /// the server environment's process
391 ///
392 /// @ingroup Environment
393 ///
394 /// @param[in] session
395 /// The session of Houdini you are interacting with.
396 /// See @ref HAPI_Sessions for more on sessions.
397 /// Pass NULL to just use the default in-process session.
398 /// <!-- default NULL -->
399 ///
400 /// @param[out] env_count
401 /// A pointer to an int to return the value in
403  int * env_count );
404 
405 /// @brief Provides a list of all of the environment variables
406 /// in the server's process
407 ///
408 /// @ingroup Environment
409 ///
410 /// @param[in] session
411 /// The session of Houdini you are interacting with.
412 /// See @ref HAPI_Sessions for more on sessions.
413 /// Pass NULL to just use the default in-process session.
414 /// <!-- default NULL -->
415 ///
416 /// @param[out] values_array
417 /// An ::HAPI_StringHandle array at least the size of length
418 ///
419 /// @param[in] start
420 /// First index of range. Must be at least @c 0 and at most
421 /// @c env_count returned by ::HAPI_GetServerEnvVarCount()
422 /// <!-- min 0 -->
423 /// <!-- max ::HAPI_GetServerEnvVarCount -->
424 /// <!-- default 0 -->
425 ///
426 /// @param[in] length
427 /// Given @c env_count returned by ::HAPI_GetServerEnvVarCount(),
428 /// length should be at least @c 0 and at most <tt>env_count - start.</tt>
429 /// <!-- default 0 -->
431  HAPI_StringHandle * values_array,
432  int start,
433  int length );
434 
435 /// @brief Set environment variable for the server process as an integer.
436 ///
437 /// Note that this may affect other sessions on the same server
438 /// process. The session parameter is mainly there to identify the
439 /// server process, not the specific session.
440 ///
441 /// For in-process sessions, this will affect the current process's
442 /// environment.
443 ///
444 /// @ingroup Environment
445 ///
446 /// @param[in] session
447 /// The session of Houdini you are interacting with.
448 /// See @ref HAPI_Sessions for more on sessions.
449 /// Pass NULL to just use the default in-process session.
450 /// <!-- default NULL -->
451 ///
452 /// @param[in] variable_name
453 /// Name of the environment variable.
454 ///
455 /// @param[in] value
456 /// The integer value.
457 ///
459  const char * variable_name,
460  int value );
461 
462 /// @brief Set environment variable for the server process as a string.
463 ///
464 /// Note that this may affect other sessions on the same server
465 /// process. The session parameter is mainly there to identify the
466 /// server process, not the specific session.
467 ///
468 /// For in-process sessions, this will affect the current process's
469 /// environment.
470 ///
471 /// @ingroup Environment
472 ///
473 /// @param[in] session
474 /// The session of Houdini you are interacting with.
475 /// See @ref HAPI_Sessions for more on sessions.
476 /// Pass NULL to just use the default in-process session.
477 /// <!-- default NULL -->
478 ///
479 /// @param[in] variable_name
480 /// Name of the environmnet variable.
481 ///
482 /// @param[in] value
483 /// The string value.
484 ///
486  const char * variable_name,
487  const char * value );
488 
489 /// @defgroup Status
490 /// Functions for reading session connection and cook status.
491 
492 /// @brief Gives back the status code for a specific status type.
493 ///
494 /// @ingroup Status
495 ///
496 /// @param[in] session
497 /// The session of Houdini you are interacting with.
498 /// See @ref HAPI_Sessions for more on sessions.
499 /// Pass NULL to just use the default in-process session.
500 /// <!-- default NULL -->
501 ///
502 /// @param[in] status_type
503 /// One of ::HAPI_StatusType.
504 ///
505 /// @param[out] status
506 /// Actual status code for the status type given. That is,
507 /// if you pass in ::HAPI_STATUS_CALL_RESULT as
508 /// status_type, you'll get back a ::HAPI_Result for this
509 /// argument. If you pass in ::HAPI_STATUS_COOK_STATE
510 /// as status_type, you'll get back a ::HAPI_State enum
511 /// for this argument.
512 ///
513 HAPI_DECL HAPI_GetStatus( const HAPI_Session * session,
514  HAPI_StatusType status_type,
515  int * status );
516 
517 /// @brief Return length of string buffer storing status string message.
518 ///
519 /// If called with ::HAPI_STATUS_COOK_RESULT this will actually
520 /// parse the node networks for the previously cooked asset(s)
521 /// and aggregate all node errors, warnings, and messages
522 /// (depending on the @c verbosity level set). Usually this is done
523 /// just for the last cooked single asset but if you load a whole
524 /// Houdini scene using ::HAPI_LoadHIPFile() then you'll have
525 /// multiple "previously cooked assets".
526 ///
527 /// You MUST call ::HAPI_GetStatusStringBufLength() before calling
528 /// ::HAPI_GetStatusString() because ::HAPI_GetStatusString() will
529 /// not return the real status string and instead return a
530 /// cached version of the string that was created inside
531 /// ::HAPI_GetStatusStringBufLength(). The reason for this is that
532 /// the length of the real status string may change between
533 /// the call to ::HAPI_GetStatusStringBufLength() and the call to
534 /// ::HAPI_GetStatusString().
535 ///
536 /// @ingroup Status
537 ///
538 /// @param[in] session
539 /// The session of Houdini you are interacting with.
540 /// See @ref HAPI_Sessions for more on sessions.
541 /// Pass NULL to just use the default in-process session.
542 /// <!-- default NULL -->
543 ///
544 /// @param[in] status_type
545 /// One of ::HAPI_StatusType.
546 ///
547 /// @param[in] verbosity
548 /// Preferred verbosity level.
549 ///
550 /// @param[out] buffer_length
551 /// Length of buffer char array ready to be filled.
552 ///
554  HAPI_StatusType status_type,
555  HAPI_StatusVerbosity verbosity,
556  int * buffer_length );
557 
558 /// @brief Return status string message.
559 ///
560 /// You MUST call ::HAPI_GetStatusStringBufLength() before calling
561 /// ::HAPI_GetStatusString() because ::HAPI_GetStatusString() will
562 /// not return the real status string and instead return a
563 /// cached version of the string that was created inside
564 /// ::HAPI_GetStatusStringBufLength(). The reason for this is that
565 /// the length of the real status string may change between
566 /// the call to ::HAPI_GetStatusStringBufLength() and the call to
567 /// ::HAPI_GetStatusString().
568 ///
569 /// @ingroup Status
570 ///
571 /// @param[in] session
572 /// The session of Houdini you are interacting with.
573 /// See @ref HAPI_Sessions for more on sessions.
574 /// Pass NULL to just use the default in-process session.
575 /// <!-- default NULL -->
576 ///
577 /// @param[in] status_type
578 /// One of ::HAPI_StatusType.
579 ///
580 /// @param[out] string_value
581 /// Buffer char array ready to be filled.
582 ///
583 /// @param[in] length
584 /// Length of the string buffer (must match size of
585 /// @p string_value - so including NULL terminator).
586 /// <!-- source ::HAPI_GetStatusStringBufLength -->
587 ///
589  HAPI_StatusType status_type,
590  char * string_value,
591  int length );
592 
593 /// @brief Compose the cook result string (errors and warnings) of a
594 /// specific node.
595 ///
596 /// This will actually parse the node network inside the given
597 /// node and return ALL errors/warnings/messages of all child nodes,
598 /// combined into a single string. If you'd like a more narrowed
599 /// search, call this function on one of the child nodes.
600 ///
601 /// You MUST call ::HAPI_ComposeNodeCookResult() before calling
602 /// ::HAPI_GetComposedNodeCookResult() because
603 /// ::HAPI_GetComposedNodeCookResult() will
604 /// not return the real result string and instead return a
605 /// cached version of the string that was created inside
606 /// ::HAPI_ComposeNodeCookResult(). The reason for this is that
607 /// the length of the real status string may change between
608 /// the call to ::HAPI_ComposeNodeCookResult() and the call to
609 /// ::HAPI_GetComposedNodeCookResult().
610 ///
611 /// @ingroup Status
612 ///
613 /// @param[in] session
614 /// The session of Houdini you are interacting with.
615 /// See @ref HAPI_Sessions for more on sessions.
616 /// Pass NULL to just use the default in-process session.
617 /// <!-- default NULL -->
618 ///
619 /// @param[in] node_id
620 /// The node id.
621 ///
622 /// @param[in] verbosity
623 /// Preferred verbosity level.
624 ///
625 /// @param[out] buffer_length
626 /// Length of buffer char array ready to be filled.
627 ///
629  HAPI_NodeId node_id,
630  HAPI_StatusVerbosity verbosity,
631  int * buffer_length );
632 
633 /// @brief Return cook result string message on a single node.
634 ///
635 /// You MUST call ::HAPI_ComposeNodeCookResult() before calling
636 /// ::HAPI_GetComposedNodeCookResult() because
637 /// ::HAPI_GetComposedNodeCookResult() will
638 /// not return the real result string and instead return a
639 /// cached version of the string that was created inside
640 /// ::HAPI_ComposeNodeCookResult(). The reason for this is that
641 /// the length of the real status string may change between
642 /// the call to ::HAPI_ComposeNodeCookResult() and the call to
643 /// ::HAPI_GetComposedNodeCookResult().
644 ///
645 /// @ingroup Status
646 ///
647 /// @param[in] session
648 /// The session of Houdini you are interacting with.
649 /// See @ref HAPI_Sessions for more on sessions.
650 /// Pass NULL to just use the default in-process session.
651 /// <!-- default NULL -->
652 ///
653 /// @param[out] string_value
654 /// Buffer char array ready to be filled.
655 ///
656 /// @param[in] length
657 /// Length of the string buffer (must match size of
658 /// @p string_value - so including NULL terminator).
659 /// <!-- source ::HAPI_ComposeNodeCookResult -->
660 ///
662  char * string_value,
663  int length );
664 
665 /// @brief Recursively check for specific errors by error code on a node.
666 ///
667 /// Note that checking for errors can be expensive because it checks
668 /// ALL child nodes within a node and then tries to do a string match
669 /// for the errors being looked for. This is why such error checking
670 /// is part of a standalone function and not done during the cooking
671 /// step.
672 ///
673 /// @ingroup Status
674 ///
675 /// @param[in] session
676 /// The session of Houdini you are interacting with.
677 /// See @ref HAPI_Sessions for more on sessions.
678 /// Pass NULL to just use the default in-process session.
679 /// <!-- default NULL -->
680 ///
681 /// @param[in] node_id
682 /// The node id.
683 ///
684 /// @param[in] errors_to_look_for
685 /// The HAPI_ErrorCode error codes (as a bitfield) to look for.
686 ///
687 /// @param[out] errors_found
688 /// Returned HAPI_ErrorCode bitfield indicating which of the
689 /// looked for errors have been found.
690 ///
692  HAPI_NodeId node_id,
693  HAPI_ErrorCodeBits errors_to_look_for,
694  HAPI_ErrorCodeBits * errors_found );
695 
696 /// @brief Clears the connection error. Should be used before starting
697 /// or creating Thrift server.
698 ///
699 /// Only available when using Thrift connections.
700 ///
701 /// @ingroup Status
702 ///
704 
705 /// @brief Return the length of string buffer storing connection error
706 /// message.
707 ///
708 /// @ingroup Status
709 ///
710 /// Only available when using Thrift connections.
711 ///
712 /// @param[out] buffer_length
713 /// Length of buffer char array ready to be filled.
714 ///
715 HAPI_DECL HAPI_GetConnectionErrorLength( int * buffer_length );
716 
717 /// @brief Return the connection error message.
718 ///
719 /// You MUST call ::HAPI_GetConnectionErrorLength() before calling
720 /// this to get the correct string length.
721 ///
722 /// Only available when using Thrift connections.
723 ///
724 /// @ingroup Status
725 ///
726 /// @param[out] string_value
727 /// Buffer char array ready to be filled.
728 ///
729 /// @param[in] length
730 /// Length of the string buffer (must match size of
731 /// string_value - so including NULL terminator).
732 /// Use ::HAPI_GetConnectionErrorLength to get this length.
733 ///
734 /// @param[in] clear
735 /// If true, will clear the error when HAPI_RESULT_SUCCESS
736 /// is returned.
737 ///
738 HAPI_DECL HAPI_GetConnectionError( char * string_value,
739  int length,
740  HAPI_Bool clear );
741 
742 /// @brief Get total number of nodes that need to cook in the current
743 /// session.
744 ///
745 /// @ingroup Status
746 ///
747 /// @param[in] session
748 /// The session of Houdini you are interacting with.
749 /// See @ref HAPI_Sessions for more on sessions.
750 /// Pass NULL to just use the default in-process session.
751 /// <!-- default NULL -->
752 ///
753 /// @param[out] count
754 /// Total cook count.
755 ///
757  int * count );
758 
759 /// @brief Get current number of nodes that have already cooked in the
760 /// current session. Note that this is a very crude approximation
761 /// of the cooking progress - it may never make it to 100% or it
762 /// might spend another hour at 100%. Use ::HAPI_GetStatusString
763 /// to get a better idea of progress if this number gets stuck.
764 ///
765 /// @ingroup Status
766 ///
767 /// @param[in] session
768 /// The session of Houdini you are interacting with.
769 /// See @ref HAPI_Sessions for more on sessions.
770 /// Pass NULL to just use the default in-process session.
771 /// <!-- default NULL -->
772 ///
773 /// @param[out] count
774 /// Current cook count.
775 ///
777  int * count );
778 
779 /// @brief Interrupt a cook or load operation.
780 ///
781 /// @ingroup Status
782 ///
783 /// @param[in] session
784 /// The session of Houdini you are interacting with.
785 /// See @ref HAPI_Sessions for more on sessions.
786 /// Pass NULL to just use the default in-process session.
787 /// <!-- default NULL -->
788 ///
789 HAPI_DECL HAPI_Interrupt( const HAPI_Session * session );
790 
791 /// @defgroup Utility
792 /// Utility math and other functions
793 
794 /// @brief Converts the transform described by a ::HAPI_TransformEuler
795 /// struct into a different transform and rotation order.
796 ///
797 /// @ingroup Utility
798 ///
799 /// @param[in] session
800 /// The session of Houdini you are interacting with.
801 /// See @ref HAPI_Sessions for more on sessions.
802 /// Pass NULL to just use the default in-process session.
803 /// <!-- default NULL -->
804 ///
805 /// @param[in] transform_in
806 /// The transform to be converted.
807 ///
808 /// @param[in] rst_order
809 /// The desired transform order of the output.
810 ///
811 /// @param[in] rot_order
812 /// The desired rotation order of the output.
813 ///
814 /// @param[out] transform_out
815 /// The converted transform.
816 ///
818  const HAPI_TransformEuler * transform_in,
819  HAPI_RSTOrder rst_order,
820  HAPI_XYZOrder rot_order,
821  HAPI_TransformEuler * transform_out );
822 
823 /// @brief Converts a 4x4 matrix into its TRS form.
824 ///
825 /// @ingroup Utility
826 ///
827 /// @param[in] session
828 /// The session of Houdini you are interacting with.
829 /// See @ref HAPI_Sessions for more on sessions.
830 /// Pass NULL to just use the default in-process session.
831 /// <!-- default NULL -->
832 ///
833 /// @param[in] matrix
834 /// A 4x4 matrix expressed in a 16 element float array.
835 ///
836 /// @param[in] rst_order
837 /// The desired transform order of the output.
838 ///
839 /// @param[out] transform_out
840 /// Used for the output.
841 ///
843  const float * matrix,
844  HAPI_RSTOrder rst_order,
845  HAPI_Transform * transform_out );
846 
847 /// @brief Converts a 4x4 matrix into its TRS form.
848 ///
849 /// @ingroup Utility
850 ///
851 /// @param[in] session
852 /// The session of Houdini you are interacting with.
853 /// See @ref HAPI_Sessions for more on sessions.
854 /// Pass NULL to just use the default in-process session.
855 /// <!-- default NULL -->
856 ///
857 /// @param[in] matrix
858 /// A 4x4 matrix expressed in a 16 element float array.
859 ///
860 /// @param[in] rst_order
861 /// The desired transform order of the output.
862 ///
863 /// @param[in] rot_order
864 /// The desired rotation order of the output.
865 ///
866 /// @param[out] transform_out
867 /// Used for the output.
868 ///
870  const float * matrix,
871  HAPI_RSTOrder rst_order,
872  HAPI_XYZOrder rot_order,
873  HAPI_TransformEuler * transform_out );
874 
875 /// @brief Converts ::HAPI_Transform into a 4x4 transform matrix.
876 ///
877 /// @ingroup Utility
878 ///
879 /// @param[in] session
880 /// The session of Houdini you are interacting with.
881 /// See @ref HAPI_Sessions for more on sessions.
882 /// Pass NULL to just use the default in-process session.
883 /// <!-- default NULL -->
884 ///
885 /// @param[in] transform
886 /// The ::HAPI_Transform you wish to convert.
887 ///
888 /// @param[out] matrix
889 /// A 16 element float array that will contain the result.
890 ///
892  const HAPI_Transform * transform,
893  float * matrix );
894 
895 /// @brief Converts ::HAPI_TransformEuler into a 4x4 transform matrix.
896 ///
897 /// @ingroup Utility
898 ///
899 /// @param[in] session
900 /// The session of Houdini you are interacting with.
901 /// See @ref HAPI_Sessions for more on sessions.
902 /// Pass NULL to just use the default in-process session.
903 /// <!-- default NULL -->
904 ///
905 /// @param[in] transform
906 /// The ::HAPI_TransformEuler you wish to convert.
907 ///
908 /// @param[out] matrix
909 /// A 16 element float array that will contain the result.
910 ///
912  const HAPI_Session * session,
913  const HAPI_TransformEuler * transform,
914  float * matrix );
915 
916 /// @brief Acquires or releases the Python interpreter lock. This is
917 /// needed if HAPI is called from Python and HAPI is in threaded
918 /// mode (see ::HAPI_Initialize()).
919 ///
920 /// The problem arises when async functions like
921 /// ::HAPI_CreateNode() may start a cooking thread that
922 /// may try to run Python code. That is, we would now have
923 /// Python running on two different threads - something not
924 /// allowed by Python by default.
925 ///
926 /// We need to tell Python to explicitly "pause" the Python state
927 /// on the client thread while we run Python in our cooking thread.
928 ///
929 /// You must call this function first with locked == true before
930 /// any async HAPI call. Then, after the async call finished,
931 /// detected via calls to ::HAPI_GetStatus(), call this method
932 /// again to release the lock with locked == false.
933 ///
934 /// @ingroup Utility
935 ///
936 /// @param[in] session
937 /// The session of Houdini you are interacting with.
938 /// See @ref HAPI_Sessions for more on sessions.
939 /// Pass NULL to just use the default in-process session.
940 /// <!-- default NULL -->
941 ///
942 /// @param[in] locked
943 /// True will acquire the interpreter lock to use it for
944 /// the HAPI cooking thread. False will release the lock
945 /// back to the client thread.
946 ///
948  HAPI_Bool locked );
949 
950 /// @defgroup Strings
951 /// Functions for handling strings.
952 
953 /// @brief Gives back the string length of the string with the
954 /// given handle.
955 ///
956 /// @ingroup Strings
957 ///
958 /// @param[in] session
959 /// The session of Houdini you are interacting with.
960 /// See @ref HAPI_Sessions for more on sessions.
961 /// Pass NULL to just use the default in-process session.
962 /// <!-- default NULL -->
963 ///
964 /// @param[in] string_handle
965 /// Handle of the string to query.
966 ///
967 /// @param[out] buffer_length
968 /// Buffer length of the queried string (including NULL
969 /// terminator).
970 ///
972  HAPI_StringHandle string_handle,
973  int * buffer_length );
974 
975 /// @brief Gives back the string value of the string with the
976 /// given handle.
977 ///
978 /// @ingroup Strings
979 ///
980 /// @param[in] session
981 /// The session of Houdini you are interacting with.
982 /// See @ref HAPI_Sessions for more on sessions.
983 /// Pass NULL to just use the default in-process session.
984 /// <!-- default NULL -->
985 ///
986 /// @param[in] string_handle
987 /// Handle of the string to query.
988 ///
989 /// @param[out] string_value
990 /// Actual string value (character array).
991 ///
992 /// @param[in] length
993 /// Length of the string buffer (must match size of
994 /// @p string_value - so including NULL terminator).
995 ///
996 HAPI_DECL HAPI_GetString( const HAPI_Session * session,
997  HAPI_StringHandle string_handle,
998  char * string_value,
999  int length );
1000 
1001 /// @brief Adds the given string to the string table and returns
1002 /// the handle. It is the responsibility of the caller to
1003 /// manage access to the string. The intended use for custom strings
1004 /// is to allow structs that reference strings to be passed in to HAPI
1005 ///
1006 /// @ingroup Strings
1007 ///
1008 /// @param[in] session
1009 /// The session of Houdini you are interacting with.
1010 /// See @ref HAPI_Sessions for more on sessions.
1011 /// Pass NULL to just use the default in-process session.
1012 /// <!-- default NULL -->
1013 ///
1014 /// @param[in] string_value
1015 /// Actual string value (character array).
1016 ///
1017 /// @param[out] handle_value
1018 /// Handle of the string that was added
1019 ///
1021  const char * string_value,
1022  int * handle_value );
1023 
1024 /// @brief Removes the specified string from the server
1025 /// and invalidates the handle
1026 ///
1027 /// @ingroup Strings
1028 ///
1029 /// @param[in] session
1030 /// The session of Houdini you are interacting with.
1031 /// See @ref HAPI_Sessions for more on sessions.
1032 /// Pass NULL to just use the default in-process session.
1033 /// <!-- default NULL -->
1034 ///
1035 /// @param[in] string_handle
1036 /// Handle of the string that was added
1037 ///
1039  const int string_handle );
1040 
1041 /// @brief Gives back the length of the buffer needed to hold
1042 /// all the values null-separated for the given string
1043 /// handles. Used with ::HAPI_GetStringBatch().
1044 ///
1045 /// @ingroup Strings
1046 ///
1047 /// @param[in] session
1048 /// The session of Houdini you are interacting with.
1049 /// See @ref HAPI_Sessions for more on sessions.
1050 /// Pass NULL to just use the default in-process session.
1051 /// <!-- default NULL -->
1052 ///
1053 /// @param[in] string_handle_array
1054 /// Array of string handles to be read.
1055 ///
1056 /// @param[in] string_handle_count
1057 /// Length of @p string_handle_array
1058 ///
1059 /// @param[out] string_buffer_size
1060 /// Buffer length required for subsequent call to
1061 /// HAPI_GetStringBatch to hold all the given
1062 /// string values null-terminated
1063 ///
1065  const int * string_handle_array,
1066  int string_handle_count,
1067  int * string_buffer_size );
1068 
1069 /// @brief Gives back the values of the given string handles.
1070 /// The given char array is filled with null-separated
1071 /// values, and the final value is null-terminated.
1072 /// Used with ::HAPI_GetStringBatchSize(). Using this function
1073 /// instead of repeated calls to ::HAPI_GetString() can be more
1074 /// more efficient for a large number of strings.
1075 ///
1076 /// @ingroup Strings
1077 ///
1078 /// @param[in] session
1079 /// The session of Houdini you are interacting with.
1080 /// See @ref HAPI_Sessions for more on sessions.
1081 /// Pass NULL to just use the default in-process session.
1082 /// <!-- default NULL -->
1083 ///
1084 /// @param[out] char_buffer
1085 /// Array of characters to hold string values.
1086 ///
1087 /// @param[in] char_array_length
1088 /// Length of @p char_array. Must be large enough to hold
1089 /// all the string values including null separators.
1090 /// <!-- min ::HAPI_GetStringBatchSize -->
1091 /// <!-- source ::HAPI_GetStringBatchSize -->
1092 ///
1093 HAPI_DECL HAPI_GetStringBatch( const HAPI_Session * session,
1094  char * char_buffer,
1095  int char_array_length );
1096 
1097 
1098 /// @defgroup Time
1099 /// Time related functions
1100 
1101 /// @brief Gets the global time of the scene. All API calls deal with
1102 /// this time to cook.
1103 ///
1104 /// @ingroup Time
1105 ///
1106 /// @param[in] session
1107 /// The session of Houdini you are interacting with.
1108 /// See @ref HAPI_Sessions for more on sessions.
1109 /// Pass NULL to just use the default in-process session.
1110 /// <!-- default NULL -->
1111 ///
1112 /// @param[out] time
1113 /// Time as a float in seconds.
1114 ///
1115 HAPI_DECL HAPI_GetTime( const HAPI_Session * session, float * time );
1116 
1117 /// @brief Sets the global time of the scene. All API calls will deal
1118 /// with this time to cook.
1119 ///
1120 /// @ingroup Time
1121 ///
1122 /// @param[in] session
1123 /// The session of Houdini you are interacting with.
1124 /// See @ref HAPI_Sessions for more on sessions.
1125 /// Pass NULL to just use the default in-process session.
1126 /// <!-- default NULL -->
1127 ///
1128 /// @param[in] time
1129 /// Time as a float in seconds.
1130 ///
1131 HAPI_DECL HAPI_SetTime( const HAPI_Session * session, float time );
1132 
1133 /// @brief Returns whether the Houdini session will use the current time in
1134 /// Houdini when cooking and retrieving data. By default this is
1135 /// disabled and the Houdini session uses time 0 (i.e. frame 1).
1136 /// In SessionSync, it is enabled by default, but can be overridden.
1137 /// Note that this function will ALWAYS return
1138 /// ::HAPI_RESULT_SUCCESS.
1139 ///
1140 /// @ingroup Time
1141 ///
1142 /// @param[in] session
1143 /// The session of Houdini you are interacting with.
1144 /// See @ref HAPI_Sessions for more on sessions.
1145 /// Pass NULL to just use the default in-process session.
1146 /// <!-- default NULL -->
1147 ///
1148 /// @param[out] enabled
1149 /// Whether use Houdini time is enabled or not.
1150 ///
1152  HAPI_Bool * enabled );
1153 
1154 /// @brief Sets whether the Houdini session should use the current time in
1155 /// Houdini when cooking and retrieving data. By default this is
1156 /// disabled and the Houdini session uses time 0 (i.e. frame 1).
1157 /// In SessionSync, it is enabled by default, but can be overridden.
1158 /// Note that this function will ALWAYS return
1159 /// ::HAPI_RESULT_SUCCESS.
1160 ///
1161 /// @ingroup Time
1162 ///
1163 /// @param[in] session
1164 /// The session of Houdini you are interacting with.
1165 /// See @ref HAPI_Sessions for more on sessions.
1166 /// Pass NULL to just use the default in-process session.
1167 /// <!-- default NULL -->
1168 ///
1169 /// @param[in] enabled
1170 /// Set to true to use Houdini time.
1171 ///
1173  HAPI_Bool enabled );
1174 
1175 /// @brief Gets the current global timeline options.
1176 ///
1177 /// @ingroup Time
1178 ///
1179 /// @param[in] session
1180 /// The session of Houdini you are interacting with.
1181 /// See @ref HAPI_Sessions for more on sessions.
1182 /// Pass NULL to just use the default in-process session.
1183 /// <!-- default NULL -->
1184 ///
1185 /// @param[out] timeline_options
1186 /// The global timeline options struct.
1187 ///
1189  HAPI_TimelineOptions * timeline_options );
1190 
1191 /// @brief Sets the global timeline options.
1192 ///
1193 /// @ingroup Time
1194 ///
1195 /// @param[in] session
1196 /// The session of Houdini you are interacting with.
1197 /// See @ref HAPI_Sessions for more on sessions.
1198 /// Pass NULL to just use the default in-process session.
1199 /// <!-- default NULL -->
1200 ///
1201 /// @param[in] timeline_options
1202 /// The global timeline options struct.
1203 ///
1205  const HAPI_Session * session,
1206  const HAPI_TimelineOptions * timeline_options );
1207 
1208 /// @defgroup Assets
1209 /// Functions for managing asset libraries
1210 
1211 /// @brief Loads a Houdini asset library (OTL) from a .otl file.
1212 /// It does NOT create anything inside the Houdini scene.
1213 ///
1214 /// @note This is when we actually check for valid licenses.
1215 ///
1216 /// The next step is to call ::HAPI_GetAvailableAssetCount()
1217 /// to get the number of assets contained in the library using the
1218 /// returned library_id. Then call ::HAPI_GetAvailableAssets()
1219 /// to get the list of available assets by name. Use the asset
1220 /// names with ::HAPI_CreateNode() to actually create
1221 /// one of these nodes in the Houdini scene and get back
1222 /// an asset_id.
1223 ///
1224 /// @note The HIP file saved using ::HAPI_SaveHIPFile() will only
1225 /// have an absolute path reference to the loaded OTL meaning
1226 /// that if the OTL is moved or renamed the HIP file won't
1227 /// load properly. It also means that if you change the OTL
1228 /// using the saved HIP scene the same OTL file will change
1229 /// as the one used with Houdini Engine.
1230 /// See @ref HAPI_Fundamentals_SavingHIPFile.
1231 ///
1232 /// @ingroup Assets
1233 ///
1234 /// @param[in] session
1235 /// The session of Houdini you are interacting with.
1236 /// See @ref HAPI_Sessions for more on sessions.
1237 /// Pass NULL to just use the default in-process session.
1238 /// <!-- default NULL -->
1239 ///
1240 /// @param[in] file_path
1241 /// Absolute path to the .otl file.
1242 ///
1243 /// @param[in] allow_overwrite
1244 /// With this true, if the library file being loaded
1245 /// contains asset definitions that have already been
1246 /// loaded they will overwrite the existing definitions.
1247 /// Otherwise, a library containing asset definitions that
1248 /// already exist will fail to load, returning a
1249 /// ::HAPI_Result of
1250 /// ::HAPI_RESULT_ASSET_DEF_ALREADY_LOADED.
1251 ///
1252 /// @param[out] library_id
1253 /// Newly loaded otl id to be used with
1254 /// ::HAPI_GetAvailableAssetCount() and
1255 /// ::HAPI_GetAvailableAssets().
1256 ///
1258  const char * file_path,
1259  HAPI_Bool allow_overwrite,
1260  HAPI_AssetLibraryId * library_id );
1261 
1262 /// @brief Loads a Houdini asset library (OTL) from memory.
1263 /// It does NOT create anything inside the Houdini scene.
1264 ///
1265 /// @note This is when we actually check for valid licenses.
1266 ///
1267 /// Please note that the performance benefit of loading a library
1268 /// from memory are negligible at best. Due to limitations of
1269 /// Houdini's library manager, there is still some disk access
1270 /// and file writes because every asset library needs to be
1271 /// saved to a real file. Use this function only as a convenience
1272 /// if you already have the library file in memory and don't wish
1273 /// to have to create your own temporary library file and then
1274 /// call ::HAPI_LoadAssetLibraryFromFile().
1275 ///
1276 /// The next step is to call ::HAPI_GetAvailableAssetCount()
1277 /// to get the number of assets contained in the library using the
1278 /// returned library_id. Then call ::HAPI_GetAvailableAssets()
1279 /// to get the list of available assets by name. Use the asset
1280 /// names with ::HAPI_CreateNode() to actually create
1281 /// one of these nodes in the Houdini scene and get back
1282 /// an asset_id.
1283 ///
1284 /// @note The saved HIP file using ::HAPI_SaveHIPFile() will
1285 /// @a contain the OTL loaded as part of its @b Embedded OTLs.
1286 /// This means that you can safely move or rename the original
1287 /// OTL file and the HIP will continue to work but if you make
1288 /// changes to the OTL while using the saved HIP the changes
1289 /// won't be saved to the original OTL.
1290 /// See @ref HAPI_Fundamentals_SavingHIPFile.
1291 ///
1292 /// @ingroup Assets
1293 ///
1294 /// @param[in] session
1295 /// The session of Houdini you are interacting with.
1296 /// See @ref HAPI_Sessions for more on sessions.
1297 /// Pass NULL to just use the default in-process session.
1298 /// <!-- default NULL -->
1299 ///
1300 /// @param[in] library_buffer
1301 /// The memory buffer containing the asset definitions
1302 /// in the same format as a standard Houdini .otl file.
1303 ///
1304 /// @param[in] library_buffer_length
1305 /// The size of the OTL memory buffer.
1306 ///
1307 /// @param[in] allow_overwrite
1308 /// With this true, if the library file being loaded
1309 /// contains asset definitions that have already been
1310 /// loaded they will overwrite the existing definitions.
1311 /// Otherwise, a library containing asset definitions that
1312 /// already exist will fail to load, returning a
1313 /// ::HAPI_Result of
1314 /// ::HAPI_RESULT_ASSET_DEF_ALREADY_LOADED.
1315 ///
1316 /// @param[out] library_id
1317 /// Newly loaded otl id to be used with
1318 /// ::HAPI_GetAvailableAssetCount() and
1319 /// ::HAPI_GetAvailableAssets().
1320 ///
1322  const char * library_buffer,
1323  int library_buffer_length,
1324  HAPI_Bool allow_overwrite,
1325  HAPI_AssetLibraryId * library_id );
1326 
1327 /// @brief Get the number of assets contained in an asset library.
1328 /// You should call ::HAPI_LoadAssetLibraryFromFile() prior to
1329 /// get a library_id.
1330 ///
1331 /// @ingroup Assets
1332 ///
1333 /// @param[in] session
1334 /// The session of Houdini you are interacting with.
1335 /// See @ref HAPI_Sessions for more on sessions.
1336 /// Pass NULL to just use the default in-process session.
1337 /// <!-- default NULL -->
1338 ///
1339 /// @param[in] library_id
1340 /// Returned by ::HAPI_LoadAssetLibraryFromFile().
1341 /// <!-- source ::HAPI_LoadAssetLibraryFromFile -->
1342 ///
1343 /// @param[out] asset_count
1344 /// The number of assets contained in this asset library.
1345 ///
1347  HAPI_AssetLibraryId library_id,
1348  int * asset_count );
1349 
1350 /// @brief Get the names of the assets contained in an asset library.
1351 ///
1352 /// The asset names will contain additional information about
1353 /// the type of asset, namespace, and version, along with the
1354 /// actual asset name. For example, if you have an Object type
1355 /// asset, in the "hapi" namespace, of version 2.0, named
1356 /// "foo", the asset name returned here will be:
1357 /// hapi::Object/foo::2.0
1358 ///
1359 /// However, you should not need to worry about this detail. Just
1360 /// pass this string directly to ::HAPI_CreateNode() to
1361 /// create the node. You can then get the pretty name
1362 /// using ::HAPI_GetAssetInfo().
1363 ///
1364 /// You should call ::HAPI_LoadAssetLibraryFromFile() prior to
1365 /// get a library_id. Then, you should call
1366 /// ::HAPI_GetAvailableAssetCount() to get the number of assets to
1367 /// know how large of a string handles array you need to allocate.
1368 ///
1369 /// @ingroup Assets
1370 ///
1371 /// @param[in] session
1372 /// The session of Houdini you are interacting with.
1373 /// See @ref HAPI_Sessions for more on sessions.
1374 /// Pass NULL to just use the default in-process session.
1375 /// <!-- default NULL -->
1376 ///
1377 /// @param[in] library_id
1378 /// Returned by ::HAPI_LoadAssetLibraryFromFile().
1379 /// <!-- source ::HAPI_LoadAssetLibraryFromFile -->
1380 ///
1381 /// @param[out] asset_names_array
1382 /// Array of string handles (integers) that should be
1383 /// at least the size of asset_count.
1384 ///
1385 /// @param[in] asset_count
1386 /// Should be the same or less than the value returned by
1387 /// ::HAPI_GetAvailableAssetCount().
1388 /// <!-- max ::HAPI_GetAvailableAssetCount -->
1389 /// <!-- source ::HAPI_GetAvailableAssetCount -->
1390 ///
1392  HAPI_AssetLibraryId library_id,
1393  HAPI_StringHandle * asset_names_array,
1394  int asset_count );
1395 
1396 /// @brief Fill an asset_info struct from a node.
1397 ///
1398 /// @ingroup Assets
1399 ///
1400 /// @param[in] session
1401 /// The session of Houdini you are interacting with.
1402 /// See @ref HAPI_Sessions for more on sessions.
1403 /// Pass NULL to just use the default in-process session.
1404 /// <!-- default NULL -->
1405 ///
1406 /// @param[in] node_id
1407 /// The node id.
1408 ///
1409 /// @param[out] asset_info
1410 /// Returned ::HAPI_AssetInfo struct.
1411 ///
1412 HAPI_DECL HAPI_GetAssetInfo( const HAPI_Session * session,
1413  HAPI_NodeId node_id,
1414  HAPI_AssetInfo * asset_info );
1415 
1416 /// @brief Get the number of asset parameters contained in an asset
1417 /// library, as well as the number of parameter int, float,
1418 /// string, and choice values.
1419 ///
1420 /// This does not create the asset in the session.
1421 /// Use this for faster querying of asset parameters compared to
1422 /// creating the asset node and querying the node's parameters.
1423 ///
1424 /// This does require ::HAPI_LoadAssetLibraryFromFile() to be
1425 /// called prior, in order to load the asset library and
1426 /// acquire library_id. Then ::HAPI_GetAvailableAssetCount and
1427 /// ::HAPI_GetAvailableAssets should be called to get the
1428 /// asset_name.
1429 ///
1430 /// @ingroup Assets
1431 ///
1432 /// @param[in] session
1433 /// The session of Houdini you are interacting with.
1434 /// See @ref HAPI_Sessions for more on sessions.
1435 /// Pass NULL to just use the default in-process session.
1436 /// <!-- default NULL -->
1437 ///
1438 /// @param[in] library_id
1439 /// Returned by ::HAPI_LoadAssetLibraryFromFile().
1440 /// <!-- source ::HAPI_LoadAssetLibraryFromFile -->
1441 ///
1442 /// @param[in] asset_name
1443 /// Name of the asset to get the parm counts for.
1444 ///
1445 /// @param[out] parm_count
1446 /// The number of parameters in the asset library.
1447 ///
1448 /// @param[out] int_value_count
1449 /// The number of int values for parameters in the asset
1450 /// library.
1451 ///
1452 /// @param[out] float_value_count
1453 /// The number of float values for parameters in the asset
1454 /// library.
1455 ///
1456 /// @param[out] string_value_count
1457 /// The number of string values for parameters in the asset
1458 /// library.
1459 ///
1460 /// @param[out] choice_value_count
1461 /// The number of choice values for parameters in the asset
1462 /// library.
1463 ///
1465  HAPI_AssetLibraryId library_id,
1466  const char * asset_name,
1467  int * parm_count,
1468  int * int_value_count,
1469  int * float_value_count,
1470  int * string_value_count,
1471  int * choice_value_count );
1472 
1473 /// @brief Fill an array of ::HAPI_ParmInfo structs with parameter
1474 /// information for the specified asset in the specified asset
1475 /// library.
1476 ///
1477 /// This does not create the asset in the session.
1478 /// Use this for faster querying of asset parameters compared to
1479 /// creating the asset node and querying the node's parameters.
1480 ///
1481 /// This does require ::HAPI_LoadAssetLibraryFromFile() to be
1482 /// called prior, in order to load the asset library and
1483 /// acquire library_id. ::HAPI_GetAssetDefinitionParmCounts should
1484 /// be called prior to acquire the count for the size of
1485 /// parm_infos_array.
1486 ///
1487 /// @ingroup Assets
1488 ///
1489 /// @param[in] session
1490 /// The session of Houdini you are interacting with.
1491 /// See @ref HAPI_Sessions for more on sessions.
1492 /// Pass NULL to just use the default in-process session.
1493 /// <!-- default NULL -->
1494 ///
1495 /// @param[in] library_id
1496 /// Returned by ::HAPI_LoadAssetLibraryFromFile().
1497 /// <!-- source ::HAPI_LoadAssetLibraryFromFile -->
1498 ///
1499 /// @param[in] asset_name
1500 /// Name of the asset to get the parm counts for.
1501 ///
1502 /// @param[out] parm_infos_array
1503 /// Array of ::HAPI_ParmInfo at least the size of
1504 /// length.
1505 ///
1506 /// @param[in] start
1507 /// First index of range. Must be at least 0 and at
1508 /// most parm_count - 1 acquired from
1509 /// ::HAPI_GetAssetInfo.
1510 /// <!-- min 0 -->
1511 /// <!-- max ::HAPI_GetAssetInfo::parm_count - 1 -->
1512 /// <!-- default 0 -->
1513 ///
1514 /// @param[in] length
1515 /// Must be at least 1 and at most parm_count - start acquired
1516 /// from ::HAPI_GetAssetInfo
1517 /// <!-- min 1 -->
1518 /// <!-- max ::HAPI_GetAssetInfo::parm_count - start -->
1519 /// <!-- source ::HAPI_GetAssetInfo::parm_count -->
1520 ///
1522  HAPI_AssetLibraryId library_id,
1523  const char * asset_name,
1524  HAPI_ParmInfo * parm_infos_array,
1525  int start,
1526  int length );
1527 
1528 /// @brief Fill arrays of parameter int values, float values, string values,
1529 /// and choice values for parameters in the specified asset in the
1530 /// specified asset library.
1531 ///
1532 /// This does not create the asset in the session.
1533 /// Use this for faster querying of asset parameters compared to
1534 /// creating the asset node and querying the node's parameters.
1535 /// Note that only default values are retrieved.
1536 ///
1537 /// This does require ::HAPI_LoadAssetLibraryFromFile() to be
1538 /// called prior, in order to load the asset library and
1539 /// acquire library_id. ::HAPI_GetAssetDefinitionParmCounts should
1540 /// be called prior to acquire the counts for the sizes of
1541 /// the values arrays.
1542 ///
1543 /// @ingroup Assets
1544 ///
1545 /// @param[in] session
1546 /// The session of Houdini you are interacting with.
1547 /// See @ref HAPI_Sessions for more on sessions.
1548 /// Pass NULL to just use the default in-process session.
1549 /// <!-- default NULL -->
1550 ///
1551 /// @param[in] library_id
1552 /// Returned by ::HAPI_LoadAssetLibraryFromFile().
1553 /// <!-- source ::HAPI_LoadAssetLibraryFromFile -->
1554 ///
1555 /// @param[in] asset_name
1556 /// Name of the asset to get the parm counts for.
1557 ///
1558 /// @param[out] int_values_array
1559 /// Array of ints at least the size of int_length.
1560 ///
1561 /// @param[in] int_start
1562 /// First index of range for int_values_array. Must be at
1563 /// least 0 and at most int_value_count - 1 acquired from
1564 /// ::HAPI_GetAssetDefinitionParmCounts.
1565 /// <!-- min 0 -->
1566 /// <!-- max ::HAPI_GetAssetDefinitionParmCounts::int_value_count - 1 -->
1567 /// <!-- default 0 -->
1568 ///
1569 /// @param[in] int_length
1570 /// Must be at least 0 and at most int_value_count - int_start
1571 /// acquired from ::HAPI_GetAssetDefinitionParmCounts.
1572 /// <!-- min 0 -->
1573 /// <!-- max ::HAPI_GetAssetDefinitionParmCounts::int_value_count - int_start -->
1574 /// <!-- source ::HAPI_GetAssetDefinitionParmCounts::int_value_count - int_start -->
1575 ///
1576 /// @param[out] float_values_array
1577 /// Array of floats at least the size of float_length.
1578 ///
1579 /// @param[in] float_start
1580 /// First index of range for float_values_array. Must be at
1581 /// least 0 and at most float_value_count - 1 acquired from
1582 /// ::HAPI_GetAssetDefinitionParmCounts.
1583 /// <!-- min 0 -->
1584 /// <!-- max ::HAPI_GetAssetDefinitionParmCounts::float_value_count - 1 -->
1585 /// <!-- default 0 -->
1586 ///
1587 /// @param[in] float_length
1588 /// Must be at least 0 and at most float_value_count -
1589 /// float_start acquired from
1590 /// ::HAPI_GetAssetDefinitionParmCounts.
1591 /// <!-- min 0 -->
1592 /// <!-- max ::HAPI_GetAssetDefinitionParmCounts::float_value_count - float_start -->
1593 /// <!-- source ::HAPI_GetAssetDefinitionParmCounts::float_value_count - float_start -->
1594 ///
1595 /// @param[in] string_evaluate
1596 /// Whether or not to evaluate the string expressions.
1597 /// For example, the string "$F" would evaluate to the
1598 /// current frame number. So, passing in evaluate = false
1599 /// would give you back the string "$F" and passing
1600 /// in evaluate = true would give you back "1" (assuming
1601 /// the current frame is 1).
1602 /// <!-- default true -->
1603 ///
1604 /// @param[out] string_values_array
1605 /// Array of HAPI_StringHandle at least the size of
1606 /// string_length.
1607 ///
1608 /// @param[in] string_start
1609 /// First index of range for string_values_array. Must be at
1610 /// least 0 and at most string_value_count - 1 acquired from
1611 /// ::HAPI_GetAssetDefinitionParmCounts.
1612 /// <!-- min 0 -->
1613 /// <!-- max ::HAPI_GetAssetDefinitionParmCounts::string_value_count - 1 -->
1614 /// <!-- default 0 -->
1615 ///
1616 /// @param[in] string_length
1617 /// Must be at least 0 and at most string_value_count -
1618 /// string_start acquired from
1619 /// ::HAPI_GetAssetDefinitionParmCounts.
1620 /// <!-- min 0 -->
1621 /// <!-- max ::HAPI_GetAssetDefinitionParmCounts::string_value_count - string_start -->
1622 /// <!-- source ::HAPI_GetAssetDefinitionParmCounts::string_value_count - string_start -->
1623 ///
1624 /// @param[out] choice_values_array
1625 /// Array of ::HAPI_ParmChoiceInfo at least the size of
1626 /// choice_length.
1627 ///
1628 /// @param[in] choice_start
1629 /// First index of range for choice_values_array. Must be at
1630 /// least 0 and at most choice_value_count - 1 acquired from
1631 /// ::HAPI_GetAssetDefinitionParmCounts.
1632 /// <!-- min 0 -->
1633 /// <!-- max ::HAPI_GetAssetDefinitionParmCounts::choice_value_count - 1 -->
1634 /// <!-- default 0 -->
1635 ///
1636 /// @param[in] choice_length
1637 /// Must be at least 0 and at most choice_value_count -
1638 /// choice_start acquired from
1639 /// ::HAPI_GetAssetDefinitionParmCounts.
1640 /// <!-- min 0 -->
1641 /// <!-- max ::HAPI_GetAssetDefinitionParmCounts::choice_value_count - choice_start -->
1642 /// <!-- source ::HAPI_GetAssetDefinitionParmCounts::choice_value_count - choice_start -->
1643 ///
1645  const HAPI_Session * session,
1646  HAPI_AssetLibraryId library_id,
1647  const char * asset_name,
1648  int * int_values_array,
1649  int int_start,
1650  int int_length,
1651  float * float_values_array,
1652  int float_start,
1653  int float_length,
1654  HAPI_Bool string_evaluate,
1655  HAPI_StringHandle * string_values_array,
1656  int string_start,
1657  int string_length,
1658  HAPI_ParmChoiceInfo * choice_values_array,
1659  int choice_start,
1660  int choice_length );
1661 
1662 /// @defgroup HipFiles Hip Files
1663 /// Functions for managing hip files
1664 
1665 /// @brief Loads a .hip file into the main Houdini scene.
1666 ///
1667 /// @note In threaded mode, this is an _async call_!
1668 ///
1669 /// @note This method will merge the HIP file into the scene. This means
1670 /// that any registered `hou.hipFile` event callbacks will be triggered
1671 /// with the `hou.hipFileEventType.BeforeMerge` and
1672 /// `hou.hipFileEventType.AfterMerge` events.
1673 ///
1674 /// @ingroup HipFiles
1675 ///
1676 /// @param[in] session
1677 /// The session of Houdini you are interacting with.
1678 /// See @ref HAPI_Sessions for more on sessions.
1679 /// Pass NULL to just use the default in-process session.
1680 /// <!-- default NULL -->
1681 ///
1682 /// @param[in] file_name
1683 /// Absolute path to the .hip file to load.
1684 ///
1685 /// @param[in] cook_on_load
1686 /// Set to true if you wish the nodes to cook as soon
1687 /// as they are created. Otherwise, you will have to
1688 /// call ::HAPI_CookNode() explicitly for each after you
1689 /// call this function.
1690 /// <!-- default false -->
1691 ///
1692 HAPI_DECL HAPI_LoadHIPFile( const HAPI_Session * session,
1693  const char * file_name,
1694  HAPI_Bool cook_on_load );
1695 
1696 /// @brief Loads a .hip file into the main Houdini scene.
1697 ///
1698 /// @note In threaded mode, this is an _async call_!
1699 ///
1700 /// @note This method will merge the HIP file into the scene. This means
1701 /// that any registered `hou.hipFile` event callbacks will be triggered
1702 /// with the `hou.hipFileEventType.BeforeMerge` and
1703 /// `hou.hipFileEventType.AfterMerge` events.
1704 ///
1705 /// @ingroup HipFiles
1706 ///
1707 /// @param[in] session
1708 /// The session of Houdini you are interacting with.
1709 /// See @ref HAPI_Sessions for more on sessions.
1710 /// Pass NULL to just use the default in-process session.
1711 ///
1712 /// @param[in] file_name
1713 /// Absolute path to the .hip file to load.
1714 ///
1715 /// @param[in] cook_on_load
1716 /// Set to true if you wish the nodes to cook as soon
1717 /// as they are created. Otherwise, you will have to
1718 /// call ::HAPI_CookNode() explicitly for each after you
1719 /// call this function.
1720 ///
1721 /// @param[out] file_id
1722 /// This parameter will be set to the HAPI_HIPFileId of the
1723 /// loaded HIP file. This can be used to lookup nodes that were
1724 /// created as a result of loading this HIP file.
1725 ///
1726 HAPI_DECL HAPI_MergeHIPFile(const HAPI_Session * session,
1727  const char * file_name,
1728  HAPI_Bool cook_on_load,
1729  HAPI_HIPFileId * file_id);
1730 
1731 /// @brief Saves a .hip file of the current Houdini scene.
1732 ///
1733 /// @ingroup HipFiles
1734 ///
1735 /// @param[in] session
1736 /// The session of Houdini you are interacting with.
1737 /// See @ref HAPI_Sessions for more on sessions.
1738 /// Pass NULL to just use the default in-process session.
1739 /// <!-- default NULL -->
1740 ///
1741 /// @param[in] file_path
1742 /// Absolute path to the .hip file to save to.
1743 ///
1744 /// @param[in] lock_nodes
1745 /// Specify whether to lock all SOP nodes before saving
1746 /// the scene file. This way, when you load the scene
1747 /// file you can see exactly the state of each SOP at
1748 /// the time it was saved instead of relying on the
1749 /// re-cook to accurately reproduce the state. It does,
1750 /// however, take a lot more space and time locking all
1751 /// nodes like this.
1752 /// <!-- default false -->
1753 ///
1754 HAPI_DECL HAPI_SaveHIPFile( const HAPI_Session * session,
1755  const char * file_path,
1756  HAPI_Bool lock_nodes );
1757 
1758 /// @brief Gets the number of nodes that were created as a result of loading a
1759 /// .hip file
1760 ///
1761 /// @ingroup HipFiles
1762 ///
1763 /// @param[in] session
1764 /// The session of Houdini you are interacting with.
1765 /// See @ref HAPI_Sessions for more on sessions.
1766 /// Pass NULL to just use the default in-process session.
1767 ///
1768 /// @param[in] id
1769 /// The HIP file id.
1770 ///
1771 /// @param[out] count
1772 /// Pointer to an int where the HIP file node count will be
1773 /// stored.
1775  HAPI_HIPFileId id,
1776  int * count);
1777 
1778 /// @brief Fills an array of ::HAPI_NodeId of nodes that were created as a
1779 /// result of loading the HIP file specified by the ::HAPI_HIPFileId
1780 ///
1781 /// @ingroup HipFiles
1782 ///
1783 /// @param[in] session
1784 /// The session of Houdini you are interacting with.
1785 /// See @ref HAPI_Sessions for more on sessions.
1786 /// Pass NULL to just use the default in-process session.
1787 ///
1788 /// @param[in] id
1789 /// The HIP file id.
1790 ///
1791 /// @param[out] node_ids
1792 /// Array of ::HAPI_NodeId at least the size of length.
1793 ///
1794 /// @param[in] length
1795 /// The number of ::HAPI_NodeId to be stored. This should be at
1796 /// least 0 and at most the count provided by
1797 /// HAPI_GetHIPFileNodeCount
1799  HAPI_HIPFileId id,
1800  HAPI_NodeId * node_ids,
1801  int length);
1802 
1803 /// @defgroup Nodes
1804 /// Functions for working with nodes
1805 
1806 /// @brief Determine if your instance of the node actually still exists
1807 /// inside the Houdini scene. This is what can be used to
1808 /// determine when the Houdini scene needs to be re-populated
1809 /// using the host application's instances of the nodes.
1810 /// Note that this function will ALWAYS return
1811 /// ::HAPI_RESULT_SUCCESS.
1812 ///
1813 /// @ingroup Nodes
1814 ///
1815 /// @param[in] session
1816 /// The session of Houdini you are interacting with.
1817 /// See @ref HAPI_Sessions for more on sessions.
1818 /// Pass NULL to just use the default in-process session.
1819 /// <!-- default NULL -->
1820 ///
1821 /// @param[in] node_id
1822 /// The node id.
1823 ///
1824 /// @param[in] unique_node_id
1825 /// The unique node id from
1826 /// ::HAPI_NodeInfo::uniqueHoudiniNodeId.
1827 /// <!-- source ::HAPI_NodeInfo::uniqueHoudiniNodeId -->
1828 ///
1829 /// @param[out] answer
1830 /// Answer to the question.
1831 ///
1832 HAPI_DECL HAPI_IsNodeValid( const HAPI_Session * session,
1833  HAPI_NodeId node_id,
1834  int unique_node_id,
1835  HAPI_Bool * answer );
1836 
1837 /// @brief Fill an ::HAPI_NodeInfo struct.
1838 ///
1839 /// @ingroup Nodes
1840 ///
1841 /// @param[in] session
1842 /// The session of Houdini you are interacting with.
1843 /// See @ref HAPI_Sessions for more on sessions.
1844 /// Pass NULL to just use the default in-process session.
1845 /// <!-- default NULL -->
1846 ///
1847 /// @param[in] node_id
1848 /// The node id.
1849 ///
1850 /// @param[out] node_info
1851 /// Return value - contains things like asset id.
1852 ///
1853 HAPI_DECL HAPI_GetNodeInfo( const HAPI_Session * session,
1854  HAPI_NodeId node_id,
1855  HAPI_NodeInfo * node_info );
1856 
1857 /// @brief Get the node absolute path in the Houdini node network or a
1858 /// relative path any other node.
1859 ///
1860 /// @ingroup Nodes
1861 ///
1862 /// @param[in] session
1863 /// The session of Houdini you are interacting with.
1864 /// See @ref HAPI_Sessions for more on sessions.
1865 /// Pass NULL to just use the default in-process session.
1866 /// <!-- default NULL -->
1867 ///
1868 /// @param[in] node_id
1869 /// The node id.
1870 ///
1871 /// @param[in] relative_to_node_id
1872 /// Set this to -1 to get the absolute path of the node_id.
1873 /// Otherwise, the path will be relative to this node id.
1874 ///
1875 /// @param[out] path
1876 /// The returned path string, valid until the next call to
1877 /// this function.
1878 ///
1879 HAPI_DECL HAPI_GetNodePath( const HAPI_Session * session,
1880  HAPI_NodeId node_id,
1881  HAPI_NodeId relative_to_node_id,
1882  HAPI_StringHandle * path );
1883 
1884 /// @brief Get the root node of a particular network type (ie. OBJ).
1885 ///
1886 /// @ingroup Nodes
1887 ///
1888 /// @param[in] session
1889 /// The session of Houdini you are interacting with.
1890 /// See @ref HAPI_Sessions for more on sessions.
1891 /// Pass NULL to just use the default in-process session.
1892 /// <!-- default NULL -->
1893 ///
1894 /// @param[in] node_type
1895 /// The node network type.
1896 ///
1897 /// @param[out] node_id
1898 /// The node id of the root node network.
1899 ///
1901  HAPI_NodeType node_type,
1902  HAPI_NodeId * node_id );
1903 
1904 /// @brief Compose a list of child nodes based on given filters.
1905 ///
1906 /// This function will only compose the list of child nodes. It will
1907 /// not return this list. After your call to this function, call
1908 /// HAPI_GetComposedChildNodeList() to get the list of child node ids.
1909 ///
1910 /// Note: When looking for all Display SOP nodes using this function,
1911 /// and using recursive mode, the recursion will stop as soon as a
1912 /// display SOP is found within each OBJ geometry network. It is
1913 /// almost never useful to get a list of ALL display SOP nodes
1914 /// recursively as they would all containt the same geometry. Even so,
1915 /// this special case only comes up if the display SOP itself is a
1916 /// subnet.
1917 ///
1918 /// @ingroup Nodes
1919 ///
1920 /// @param[in] session
1921 /// The session of Houdini you are interacting with.
1922 /// See @ref HAPI_Sessions for more on sessions.
1923 /// Pass NULL to just use the default in-process session.
1924 /// <!-- default NULL -->
1925 ///
1926 /// @param[in] parent_node_id
1927 /// The node id of the parent node.
1928 ///
1929 /// @param[in] node_type_filter
1930 /// The node type by which to filter the children.
1931 ///
1932 /// @param[in] node_flags_filter
1933 /// The node flags by which to filter the children.
1934 ///
1935 /// @param[in] recursive
1936 /// Whether or not to compose the list recursively.
1937 ///
1938 /// @param[out] count
1939 /// The number of child nodes composed. Use this as the
1940 /// argument to ::HAPI_GetComposedChildNodeList().
1941 ///
1943  HAPI_NodeId parent_node_id,
1944  HAPI_NodeTypeBits node_type_filter,
1945  HAPI_NodeFlagsBits node_flags_filter,
1946  HAPI_Bool recursive,
1947  int * count );
1948 
1949 /// @brief Get the composed list of child node ids from the previous call
1950 /// to HAPI_ComposeChildNodeList().
1951 ///
1952 /// @ingroup Nodes
1953 ///
1954 /// @param[in] session
1955 /// The session of Houdini you are interacting with.
1956 /// See @ref HAPI_Sessions for more on sessions.
1957 /// Pass NULL to just use the default in-process session.
1958 /// <!-- default NULL -->
1959 ///
1960 /// @param[in] parent_node_id
1961 /// The node id of the parent node.
1962 ///
1963 /// @param[out] child_node_ids_array
1964 /// The array of ::HAPI_NodeId for the child nodes.
1965 ///
1966 /// @param[in] count
1967 /// The number of children in the composed list. MUST match
1968 /// the count returned by HAPI_ComposeChildNodeList().
1969 /// <!-- source ::HAPI_ComposeChildNodeList -->
1970 /// <!-- min ::HAPI_ComposeChildNodeList -->
1971 /// <!-- max ::HAPI_ComposeChildNodeList -->
1972 ///
1974  HAPI_NodeId parent_node_id,
1975  HAPI_NodeId * child_node_ids_array,
1976  int count );
1977 
1978 /// @brief Create a node inside a node network. Nodes created this way
1979 /// will have their ::HAPI_NodeInfo::createdPostAssetLoad set
1980 /// to true.
1981 ///
1982 /// @note In threaded mode, this is an _async call_!
1983 ///
1984 /// @note This is also when we actually check for valid licenses.
1985 ///
1986 /// This API will invoke the cooking thread if threading is
1987 /// enabled. This means it will return immediately with a call
1988 /// result of ::HAPI_RESULT_SUCCESS, even if fed garbage. Use
1989 /// the status and cooking count APIs under DIAGNOSTICS to get
1990 /// a sense of the progress. All other API calls will block
1991 /// until the creation (and, optionally, the first cook)
1992 /// of the node has finished.
1993 ///
1994 /// Also note that the cook result won't be of type
1995 /// ::HAPI_STATUS_CALL_RESULT like all calls (including this one).
1996 /// Whenever the threading cook is done it will fill the
1997 /// @a cook result which is queried using
1998 /// ::HAPI_STATUS_COOK_RESULT.
1999 ///
2000 /// @ingroup Nodes
2001 ///
2002 /// @param[in] session
2003 /// The session of Houdini you are interacting with.
2004 /// See @ref HAPI_Sessions for more on sessions.
2005 /// Pass NULL to just use the default in-process session.
2006 /// <!-- default NULL -->
2007 ///
2008 /// @param[in] parent_node_id
2009 /// The parent node network's node id or -1 if the parent
2010 /// network is the manager (top-level) node. In that case,
2011 /// the manager must be identified by the table name in the
2012 /// operator_name.
2013 /// <!-- min -1 -->
2014 /// <!-- default -1 -->
2015 ///
2016 /// @param[in] operator_name
2017 /// The name of the node operator type.
2018 ///
2019 /// If you passed parent_node_id == -1, then the operator_name
2020 /// has to include the table name (ie. Object/ or Sop/).
2021 /// This is the common case for when creating asset nodes
2022 /// from a loaded asset library. In that case, just pass
2023 /// whatever ::HAPI_GetAvailableAssets() returns.
2024 ///
2025 /// If you have a parent_node_id then you should
2026 /// include only the namespace, name, and version.
2027 ///
2028 /// For example, lets say you have an Object type asset, in
2029 /// the "hapi" namespace, of version 2.0, named "foo". If
2030 /// you pass parent_node_id == -1, then set the operator_name
2031 /// as "Object/hapi::foo::2.0". Otherwise, if you have a valid
2032 /// parent_node_id, then just pass operator_name as
2033 /// "hapi::foo::2.0".
2034 ///
2035 /// @param[in] node_label
2036 /// (Optional) The label of the newly created node.
2037 /// <!-- default NULL -->
2038 ///
2039 /// @param[in] cook_on_creation
2040 /// Set whether the node should cook once created or not.
2041 /// <!-- default false -->
2042 ///
2043 /// @param[out] new_node_id
2044 /// The returned node id of the just-created node.
2045 ///
2046 HAPI_DECL HAPI_CreateNode( const HAPI_Session * session,
2047  HAPI_NodeId parent_node_id,
2048  const char * operator_name,
2049  const char * node_label,
2050  HAPI_Bool cook_on_creation,
2051  HAPI_NodeId * new_node_id );
2052 
2053 /// @brief Creates a simple geometry SOP node that can accept geometry input.
2054 /// This will create a dummy OBJ node with a Null SOP inside that
2055 /// you can set the geometry of using the geometry SET APIs.
2056 /// You can then connect this node to any other node as a geometry
2057 /// input.
2058 ///
2059 /// Note that when saving the Houdini scene using
2060 /// ::HAPI_SaveHIPFile() the nodes created with this
2061 /// method will be green and will start with the name "input".
2062 ///
2063 /// @ingroup Nodes
2064 ///
2065 /// @param[in] session
2066 /// The session of Houdini you are interacting with.
2067 /// See @ref HAPI_Sessions for more on sessions.
2068 /// Pass NULL to just use the default in-process session.
2069 /// <!-- default NULL -->
2070 ///
2071 /// @param[out] node_id
2072 /// Newly created node's id. Use ::HAPI_GetNodeInfo()
2073 /// to get more information about the node.
2074 ///
2075 /// @param[in] name
2076 /// Give this input node a name for easy debugging.
2077 /// The node's parent OBJ node and the Null SOP node will both
2078 /// get this given name with "input_" prepended.
2079 /// You can also pass NULL in which case the name will
2080 /// be "input#" where # is some number.
2081 /// <!-- default NULL -->
2082 ///
2084  HAPI_NodeId * node_id,
2085  const char * name );
2086 
2087 /// @defgroup HeightFields Height Fields
2088 /// Functions for creating and inspecting HAPI session state.
2089 
2090 /// @deprecated Use HAPI_CreateHeightFieldInput() instead.
2091 ///
2092 /// @brief Creates the required node hierarchy needed for Heightfield inputs.
2093 ///
2094 /// Note that when saving the Houdini scene using
2095 /// ::HAPI_SaveHIPFile() the nodes created with this
2096 /// method will be green and will start with the name "input".
2097 ///
2098 /// Note also that this uses center sampling. Use
2099 /// ::HAPI_CreateHeightFieldInput to specify corner sampling.
2100 ///
2101 /// @ingroup HeightFields
2102 ///
2103 /// @param[in] session
2104 /// The session of Houdini you are interacting with.
2105 /// See @ref HAPI_Sessions for more on sessions.
2106 /// Pass NULL to just use the default in-process session.
2107 /// <!-- default NULL -->
2108 ///
2109 /// @param[in] parent_node_id
2110 /// The parent node network's node id or -1 if the parent
2111 /// network is the manager (top-level) node. In that case,
2112 /// the manager must be identified by the table name in the
2113 /// operator_name.
2114 /// <!-- min -1 -->
2115 /// <!-- default -1 -->
2116 ///
2117 /// @param[in] name
2118 /// Give this input node a name for easy debugging.
2119 /// The node's parent OBJ node and the Null SOP node will both
2120 /// get this given name with "input_" prepended.
2121 /// You can also pass NULL in which case the name will
2122 /// be "input#" where # is some number.
2123 /// <!-- default NULL -->
2124 ///
2125 /// @param[in] xsize
2126 /// size of the heightfield in X
2127 ///
2128 /// @param[in] ysize
2129 /// size of the heightfield in y
2130 ///
2131 /// @param[in] voxelsize
2132 /// Size of the voxel
2133 ///
2134 /// @param[out] heightfield_node_id
2135 /// Newly created node id for the Heightfield node.
2136 /// Use ::HAPI_GetNodeInfo() to get more information about
2137 /// the node.
2138 ///
2139 /// @param[out] height_node_id
2140 /// Newly created node id for the height volume.
2141 /// Use ::HAPI_GetNodeInfo() to get more information about the node.
2142 ///
2143 /// @param[out] mask_node_id
2144 /// Newly created node id for the mask volume.
2145 /// Use ::HAPI_GetNodeInfo() to get more information about the
2146 /// node.
2147 ///
2148 /// @param[out] merge_node_id
2149 /// Newly created merge node id.
2150 /// The merge node can be used to connect additional input masks.
2151 /// Use ::HAPI_GetNodeInfo() to get more information about the node.
2152 ///
2153 HAPI_DECL_DEPRECATED( 3.3.5, 18.0.162 )
2155  HAPI_NodeId parent_node_id,
2156  const char * name,
2157  int xsize,
2158  int ysize,
2159  float voxelsize,
2160  HAPI_NodeId * heightfield_node_id,
2161  HAPI_NodeId * height_node_id,
2162  HAPI_NodeId * mask_node_id,
2163  HAPI_NodeId * merge_node_id );
2164 
2165 /// @brief Creates the required node hierarchy needed for heightfield inputs.
2166 ///
2167 /// Note that when saving the Houdini scene using
2168 /// ::HAPI_SaveHIPFile() the nodes created with this
2169 /// method will be green and will start with the name "input".
2170 ///
2171 /// @ingroup HeightFields
2172 ///
2173 /// @param[in] session
2174 /// The session of Houdini you are interacting with.
2175 /// See @ref HAPI_Sessions for more on sessions.
2176 /// Pass NULL to just use the default in-process session.
2177 /// <!-- default NULL -->
2178 ///
2179 /// @param[in] parent_node_id
2180 /// The parent node network's node id or -1 if the parent
2181 /// network is the manager (top-level) node. In that case,
2182 /// the manager must be identified by the table name in the
2183 /// operator_name.
2184 /// <!-- min -1 -->
2185 /// <!-- default -1 -->
2186 ///
2187 /// @param[in] name
2188 /// Give this input node a name for easy debugging.
2189 /// The node's parent OBJ node and the Null SOP node will both
2190 /// get this given name with "input_" prepended.
2191 /// You can also pass NULL in which case the name will
2192 /// be "input#" where # is some number.
2193 /// <!-- default NULL -->
2194 ///
2195 /// @param[in] xsize
2196 /// size of the heightfield in X
2197 ///
2198 /// @param[in] ysize
2199 /// size of the heightfield in y
2200 ///
2201 /// @param[in] voxelsize
2202 /// Size of the voxel
2203 ///
2204 /// @param[in] sampling
2205 /// Type of sampling which should be either center or corner.
2206 ///
2207 /// @param[out] heightfield_node_id
2208 /// Newly created node id for the heightfield node.
2209 /// Use ::HAPI_GetNodeInfo() to get more information about
2210 /// the node.
2211 ///
2212 /// @param[out] height_node_id
2213 /// Newly created node id for the height volume.
2214 /// Use ::HAPI_GetNodeInfo() to get more information about the node.
2215 ///
2216 /// @param[out] mask_node_id
2217 /// Newly created node id for the mask volume.
2218 /// Use ::HAPI_GetNodeInfo() to get more information about the
2219 /// node.
2220 ///
2221 /// @param[out] merge_node_id
2222 /// Newly created merge node id.
2223 /// The merge node can be used to connect additional input masks.
2224 /// Use ::HAPI_GetNodeInfo() to get more information about the node.
2225 ///
2227  HAPI_NodeId parent_node_id,
2228  const char * name,
2229  int xsize,
2230  int ysize,
2231  float voxelsize,
2232  HAPI_HeightFieldSampling sampling,
2233  HAPI_NodeId * heightfield_node_id,
2234  HAPI_NodeId * height_node_id,
2235  HAPI_NodeId * mask_node_id,
2236  HAPI_NodeId * merge_node_id );
2237 
2238 /// @brief Creates a volume input node that can be used with Heightfields
2239 ///
2240 /// Note that when saving the Houdini scene using
2241 /// ::HAPI_SaveHIPFile() the nodes created with this
2242 /// method will be green and will start with the name "input".
2243 ///
2244 /// @ingroup HeightFields
2245 ///
2246 /// @param[in] session
2247 /// The session of Houdini you are interacting with.
2248 /// See @ref HAPI_Sessions for more on sessions.
2249 /// Pass NULL to just use the default in-process session.
2250 /// <!-- default NULL -->
2251 ///
2252 /// @param[in] parent_node_id
2253 /// The parent node network's node id or -1 if the parent
2254 /// network is the manager (top-level) node. In that case,
2255 /// the manager must be identified by the table name in the
2256 /// operator_name.
2257 /// <!-- min -1 -->
2258 /// <!-- default -1 -->
2259 ///
2260 /// @param[out] new_node_id
2261 /// Newly created node id for the volume.
2262 /// Use ::HAPI_GetNodeInfo() to get more information about the
2263 /// node.
2264 ///
2265 /// @param[in] name
2266 /// The name of the volume to create.
2267 /// You can also pass NULL in which case the name will
2268 /// be "input#" where # is some number.
2269 /// <!-- default NULL -->
2270 ///
2271 /// @param[in] xsize
2272 /// size of the heightfield in X
2273 ///
2274 /// @param[in] ysize
2275 /// size of the heightfield in y
2276 ///
2277 /// @param[in] voxelsize
2278 /// Size of the voxel
2279 ///
2281  HAPI_NodeId parent_node_id,
2282  HAPI_NodeId * new_node_id,
2283  const char * name,
2284  int xsize,
2285  int ysize,
2286  float voxelsize );
2287 
2288 /// @brief Initiate a cook on this node. Note that this may trigger
2289 /// cooks on other nodes if they are connected.
2290 ///
2291 /// @note In threaded mode, this is an _async call_!
2292 ///
2293 /// This API will invoke the cooking thread if threading is
2294 /// enabled. This means it will return immediately. Use
2295 /// the status and cooking count APIs under DIAGNOSTICS to get
2296 /// a sense of the progress. All other API calls will block
2297 /// until the cook operation has finished.
2298 ///
2299 /// Also note that the cook result won't be of type
2300 /// ::HAPI_STATUS_CALL_RESULT like all calls (including this one).
2301 /// Whenever the threading cook is done it will fill the
2302 /// @a cook result which is queried using
2303 /// ::HAPI_STATUS_COOK_RESULT.
2304 ///
2305 /// @ingroup Nodes
2306 ///
2307 /// @param[in] session
2308 /// The session of Houdini you are interacting with.
2309 /// See @ref HAPI_Sessions for more on sessions.
2310 /// Pass NULL to just use the default in-process session.
2311 /// <!-- default NULL -->
2312 ///
2313 /// @param[in] node_id
2314 /// The node id.
2315 ///
2316 /// @param[in] cook_options
2317 /// The cook options. Pass in NULL to use the global
2318 /// cook options that you specified when calling
2319 /// ::HAPI_Initialize().
2320 ///
2321 HAPI_DECL HAPI_CookNode( const HAPI_Session * session,
2322  HAPI_NodeId node_id,
2323  const HAPI_CookOptions * cook_options );
2324 
2325 /// @brief Delete a node from a node network. Only nodes with their
2326 /// ::HAPI_NodeInfo::createdPostAssetLoad set to true can be
2327 /// deleted this way.
2328 ///
2329 /// @ingroup Nodes
2330 ///
2331 /// @param[in] session
2332 /// The session of Houdini you are interacting with.
2333 /// See @ref HAPI_Sessions for more on sessions.
2334 /// Pass NULL to just use the default in-process session.
2335 /// <!-- default NULL -->
2336 ///
2337 /// @param[in] node_id
2338 /// The node to delete.
2339 ///
2340 HAPI_DECL HAPI_DeleteNode( const HAPI_Session * session,
2341  HAPI_NodeId node_id );
2342 
2343 /// @brief Rename a node that you created. Only nodes with their
2344 /// ::HAPI_NodeInfo::createdPostAssetLoad set to true can be
2345 /// renamed this way.
2346 ///
2347 /// @ingroup Nodes
2348 ///
2349 /// @param[in] session
2350 /// The session of Houdini you are interacting with.
2351 /// See @ref HAPI_Sessions for more on sessions.
2352 /// Pass NULL to just use the default in-process session.
2353 /// <!-- default NULL -->
2354 ///
2355 /// @param[in] node_id
2356 /// The node to rename.
2357 ///
2358 /// @param[in] new_name
2359 /// The new node name.
2360 ///
2361 HAPI_DECL HAPI_RenameNode( const HAPI_Session * session,
2362  HAPI_NodeId node_id,
2363  const char * new_name );
2364 
2365 /// @brief Connect two nodes together.
2366 ///
2367 /// @param[in] session
2368 /// The session of Houdini you are interacting with.
2369 /// See @ref HAPI_Sessions for more on sessions.
2370 /// Pass NULL to just use the default in-process session.
2371 /// <!-- default NULL -->
2372 ///
2373 /// @ingroup Nodes
2374 ///
2375 /// @param[in] node_id
2376 /// The node whom's input to connect to.
2377 ///
2378 /// @param[in] input_index
2379 /// The input index. Should be between 0 and the
2380 /// to_node's ::HAPI_NodeInfo::inputCount - 1.
2381 /// <!-- min 0 -->
2382 ///
2383 /// @param[in] node_id_to_connect
2384 /// The node to connect to node_id's input.
2385 ///
2386 /// @param[in] output_index
2387 /// The output index. Should be between 0 and the
2388 /// to_node's ::HAPI_NodeInfo::outputCount - 1.
2389 /// <!-- min 0 -->
2390 ///
2392  HAPI_NodeId node_id,
2393  int input_index,
2394  HAPI_NodeId node_id_to_connect,
2395  int output_index );
2396 
2397 /// @brief Disconnect a node input.
2398 ///
2399 /// @param[in] session
2400 /// The session of Houdini you are interacting with.
2401 /// See @ref HAPI_Sessions for more on sessions.
2402 /// Pass NULL to just use the default in-process session.
2403 /// <!-- default NULL -->
2404 ///
2405 /// @ingroup Nodes
2406 ///
2407 /// @param[in] node_id
2408 /// The node whom's input to disconnect.
2409 ///
2410 /// @param[in] input_index
2411 /// The input index. Should be between 0 and the
2412 /// to_node's ::HAPI_NodeInfo::inputCount - 1.
2413 /// <!-- min 0 -->
2414 ///
2416  HAPI_NodeId node_id,
2417  int input_index );
2418 
2419 /// @brief Query which node is connected to another node's input.
2420 ///
2421 /// @param[in] session
2422 /// The session of Houdini you are interacting with.
2423 /// See @ref HAPI_Sessions for more on sessions.
2424 /// Pass NULL to just use the default in-process session.
2425 /// <!-- default NULL -->
2426 ///
2427 /// @ingroup Nodes
2428 ///
2429 /// @param[in] node_to_query
2430 /// The node to query.
2431 ///
2432 /// @param[in] input_index
2433 /// The input index. Should be between 0 and the
2434 /// to_node's ::HAPI_NodeInfo::inputCount - 1.
2435 /// <!-- min 0 -->
2436 ///
2437 /// @param[out] connected_node_id
2438 /// The node id of the connected node to this input. If
2439 /// nothing is connected then -1 will be returned.
2440 ///
2441 HAPI_DECL HAPI_QueryNodeInput( const HAPI_Session * session,
2442  HAPI_NodeId node_to_query,
2443  int input_index,
2444  HAPI_NodeId * connected_node_id );
2445 
2446 /// @brief Get the name of an node's input. This function will return
2447 /// a string handle for the name which will be valid (persist)
2448 /// until the next call to this function.
2449 ///
2450 /// @ingroup Nodes
2451 ///
2452 /// @param[in] session
2453 /// The session of Houdini you are interacting with.
2454 /// See @ref HAPI_Sessions for more on sessions.
2455 /// Pass NULL to just use the default in-process session.
2456 /// <!-- default NULL -->
2457 ///
2458 /// @param[in] node_id
2459 /// The node id.
2460 ///
2461 /// @param[in] input_idx
2462 /// The input index. Should be between 0 and the
2463 /// node_to_query's ::HAPI_NodeInfo::inputCount - 1.
2464 /// <!-- min 0 -->
2465 ///
2466 /// @param[out] name
2467 /// Input name string handle return value - valid until
2468 /// the next call to this function.
2469 ///
2471  HAPI_NodeId node_id,
2472  int input_idx,
2473  HAPI_StringHandle * name );
2474 
2475 /// @brief Disconnect all of the node's output connections at the output index.
2476 ///
2477 /// @ingroup Nodes
2478 ///
2479 /// @param[in] session
2480 /// The session of Houdini you are interacting with.
2481 /// See @ref HAPI_Sessions for more on sessions.
2482 /// Pass NULL to just use the default in-process session.
2483 /// <!-- default NULL -->
2484 ///
2485 /// @param[in] node_id
2486 /// The node whom's outputs to disconnect.
2487 ///
2488 /// @param[in] output_index
2489 /// The output index. Should be between 0 and the
2490 /// to_node's ::HAPI_NodeInfo::outputCount.
2491 /// <!-- min 0 -->
2492 ///
2494  HAPI_NodeId node_id,
2495  int output_index );
2496 
2497 /// @brief Get the number of nodes currently connected to the given node at
2498 /// the output index.
2499 ///
2500 /// @ingroup Nodes
2501 ///
2502 /// Use the @c count returned by this function to get the
2503 /// ::HAPI_NodeId of connected nodes using
2504 /// ::HAPI_QueryNodeOutputConnectedNodes().
2505 ///
2506 /// @param[in] session
2507 /// The session of Houdini you are interacting with.
2508 /// See @ref HAPI_Sessions for more on sessions.
2509 /// Pass NULL to just use the default in-process session.
2510 /// <!-- default NULL -->
2511 ///
2512 /// @param[in] node_id
2513 /// The node id.
2514 ///
2515 /// @param[in] output_idx
2516 /// The output index. Should be between 0 and the
2517 /// to_node's ::HAPI_NodeInfo::outputCount - 1.
2518 /// <!-- min 0 -->
2519 /// <!-- max ::HAPI_NodeInfo::outputCount - 1 -->
2520 ///
2521 /// @param[in] into_subnets
2522 /// Whether to search by diving into subnets.
2523 /// <!-- default true -->
2524 ///
2525 /// @param[in] through_dots
2526 /// Whether to search through dots.
2527 /// <!-- default true -->
2528 ///
2529 /// @param[out] connected_count
2530 /// The number of nodes currently connected to this node at
2531 /// given output index. Use this count with a call to
2532 /// ::HAPI_QueryNodeOutputConnectedNodes() to get list of
2533 /// connected nodes.
2534 ///
2536  HAPI_NodeId node_id,
2537  int output_idx,
2538  HAPI_Bool into_subnets,
2539  HAPI_Bool through_dots,
2540  int * connected_count );
2541 
2542 /// @brief Get the ids of nodes currently connected to the given node
2543 /// at the output index.
2544 ///
2545 /// Use the @c connected_count returned by
2546 /// ::HAPI_QueryNodeOutputConnectedCount().
2547 ///
2548 /// @ingroup Nodes
2549 ///
2550 /// @param[in] session
2551 /// The session of Houdini you are interacting with.
2552 /// See @ref HAPI_Sessions for more on sessions.
2553 /// Pass NULL to just use the default in-process session.
2554 /// <!-- default NULL -->
2555 ///
2556 /// @param[in] node_id
2557 /// The node id.
2558 ///
2559 /// @param[in] output_idx
2560 /// The output index. Should be between 0 and the
2561 /// to_node's ::HAPI_NodeInfo::outputCount - 1.
2562 /// <!-- min 0 -->
2563 /// <!-- max ::HAPI_NodeInfo::outputCount - 1 -->
2564 ///
2565 /// @param[in] into_subnets
2566 /// Whether to search by diving into subnets.
2567 /// <!-- default true -->
2568 ///
2569 /// @param[in] through_dots
2570 /// Whether to search through dots.
2571 /// <!-- default true -->
2572 ///
2573 /// @param[out] connected_node_ids_array
2574 /// Array of ::HAPI_NodeId at least the size of @c length.
2575 ///
2576 /// @param[in] start
2577 /// At least @c 0 and at most @c connected_count returned by
2578 /// ::HAPI_QueryNodeOutputConnectedCount().
2579 /// <!-- min 0 -->
2580 /// <!-- max ::HAPI_QueryNodeOutputConnectedCount -->
2581 /// <!-- default 0 -->
2582 ///
2583 /// @param[in] length
2584 /// Given @c connected_count returned by
2585 /// ::HAPI_QueryNodeOutputConnectedCount(), @c length should
2586 /// be at least @c 1 and at most <tt>connected_count - start</tt>.
2587 /// <!-- min 1 -->
2588 /// <!-- max ::HAPI_QueryNodeOutputConnectedCount - start -->
2589 /// <!-- source ::HAPI_QueryNodeOutputConnectedCount - start -->
2590 ///
2592  HAPI_NodeId node_id,
2593  int output_idx,
2594  HAPI_Bool into_subnets,
2595  HAPI_Bool through_dots,
2596  HAPI_NodeId * connected_node_ids_array,
2597  int start, int length );
2598 
2599 /// @brief Get the name of an node's output. This function will return
2600 /// a string handle for the name which will be valid (persist)
2601 /// until the next call to this function.
2602 ///
2603 /// @ingroup Nodes
2604 ///
2605 /// @param[in] session
2606 /// The session of Houdini you are interacting with.
2607 /// See @ref HAPI_Sessions for more on sessions.
2608 /// Pass NULL to just use the default in-process session.
2609 /// <!-- default NULL -->
2610 ///
2611 /// @param[in] node_id
2612 /// The node id.
2613 ///
2614 /// @param[in] output_idx
2615 /// The output index. Should be between 0 and the
2616 /// to_node's ::HAPI_NodeInfo::outputCount - 1.
2617 /// <!-- min 0 -->
2618 /// <!-- max ::HAPI_NodeInfo::outputCount - 1 -->
2619 ///
2620 /// @param[out] name
2621 /// Output name string handle return value - valid until
2622 /// the next call to this function.
2623 ///
2625  HAPI_NodeId node_id,
2626  int output_idx,
2627  HAPI_StringHandle * name );
2628 
2629 /// @brief Gets the node id of an output node in a SOP network.
2630 ///
2631 /// @ingroup Nodes
2632 ///
2633 /// @param[in] session
2634 /// The session of Houdini you are interacting with.
2635 /// See @ref HAPI_Sessions for more on sessions.
2636 /// Pass NULL to just use the default in-process session.
2637 /// <!-- default NULL -->
2638 ///
2639 /// @param[in] node_id
2640 /// The node id of a SOP node with at least one output node. The
2641 /// total number of node outputs can be found from the node's
2642 /// ::HAPI_NodeInfo::outputCount
2643 ///
2644 /// @param[in] output
2645 /// The output index. Should be between 0 and the node's
2646 /// ::HAPI_NodeInfo::outputCount - 1.
2647 /// <!-- min 0 -->
2648 /// <!-- max ::HAPI_NodeInfo::outputCount - 1 -->
2649 ///
2650 /// @param[out] output_node_id
2651 /// Pointer to a HAPI_NodeId where the node id of the output
2652 /// node will be stored.
2654  HAPI_NodeId node_id,
2655  int output,
2656  HAPI_NodeId * output_node_id );
2657 
2658 /// @defgroup Parms Parms
2659 /// Functions for wroking with Node parameters (parms)
2660 
2661 /// @brief Fill an array of ::HAPI_ParmInfo structs with parameter
2662 /// information from the asset instance node.
2663 ///
2664 /// @ingroup Parms
2665 ///
2666 /// @param[in] session
2667 /// The session of Houdini you are interacting with.
2668 /// See @ref HAPI_Sessions for more on sessions.
2669 /// Pass NULL to just use the default in-process session.
2670 /// <!-- default NULL -->
2671 ///
2672 /// @param[in] node_id
2673 /// The node id.
2674 ///
2675 /// @param[out] parm_infos_array
2676 /// Array of ::HAPI_ParmInfo at least the size of
2677 /// length.
2678 ///
2679 /// @param[in] start
2680 /// First index of range. Must be at least 0 and at
2681 /// most ::HAPI_NodeInfo::parmCount - 1.
2682 /// <!-- min 0 -->
2683 /// <!-- max ::HAPI_NodeInfo::parmCount - 1 -->
2684 /// <!-- default 0 -->
2685 ///
2686 /// @param[in] length
2687 /// Must be at least 1 and at most
2688 /// ::HAPI_NodeInfo::parmCount - start.
2689 /// <!-- min 1 -->
2690 /// <!-- max ::HAPI_NodeInfo::parmCount - start -->
2691 /// <!-- source ::HAPI_NodeInfo::parmCount - start -->
2692 ///
2693 HAPI_DECL HAPI_GetParameters( const HAPI_Session * session,
2694  HAPI_NodeId node_id,
2695  HAPI_ParmInfo * parm_infos_array,
2696  int start, int length );
2697 
2698 /// @brief Get the parm info of a parameter by parm id.
2699 ///
2700 /// @ingroup Parms
2701 ///
2702 /// @param[in] session
2703 /// The session of Houdini you are interacting with.
2704 /// See @ref HAPI_Sessions for more on sessions.
2705 /// Pass NULL to just use the default in-process session.
2706 /// <!-- default NULL -->
2707 ///
2708 /// @param[in] node_id
2709 /// The node id.
2710 ///
2711 /// @param[in] parm_id
2712 /// The parm id.
2713 ///
2714 /// @param[out] parm_info
2715 /// The returned parm info.
2716 ///
2717 HAPI_DECL HAPI_GetParmInfo( const HAPI_Session * session,
2718  HAPI_NodeId node_id,
2719  HAPI_ParmId parm_id,
2720  HAPI_ParmInfo * parm_info );
2721 
2722 /// @brief All parameter APIs require a ::HAPI_ParmId but if you know the
2723 /// parameter you wish to operate on by name than you can use
2724 /// this function to get its ::HAPI_ParmId. If the parameter with
2725 /// the given name is not found the parameter id returned
2726 /// will be -1.
2727 ///
2728 /// @ingroup Parms
2729 ///
2730 /// @param[in] session
2731 /// The session of Houdini you are interacting with.
2732 /// See @ref HAPI_Sessions for more on sessions.
2733 /// Pass NULL to just use the default in-process session.
2734 /// <!-- default NULL -->
2735 ///
2736 /// @param[in] node_id
2737 /// The node id.
2738 ///
2739 /// @param[in] parm_name
2740 /// The parm name.
2741 ///
2742 /// @param[out] parm_id
2743 /// The return value. The parameter's ::HAPI_ParmId. If
2744 /// the parameter with the given name is not found the
2745 /// parameter id returned will be -1.
2746 ///
2748  HAPI_NodeId node_id,
2749  const char * parm_name,
2750  HAPI_ParmId * parm_id );
2751 
2752 /// @brief Get the parm info of a parameter by name.
2753 ///
2754 /// @ingroup Parms
2755 ///
2756 /// @param[in] session
2757 /// The session of Houdini you are interacting with.
2758 /// See @ref HAPI_Sessions for more on sessions.
2759 /// Pass NULL to just use the default in-process session.
2760 /// <!-- default NULL -->
2761 ///
2762 /// @param[in] node_id
2763 /// The node id.
2764 ///
2765 /// @param[in] parm_name
2766 /// The parm name.
2767 ///
2768 /// @param[out] parm_info
2769 /// The returned parm info.
2770 ///
2772  HAPI_NodeId node_id,
2773  const char * parm_name,
2774  HAPI_ParmInfo * parm_info );
2775 
2776 /// @brief Get the tag name on a parameter given an index.
2777 ///
2778 /// @ingroup Parms
2779 ///
2780 /// @param[in] session
2781 /// The session of Houdini you are interacting with.
2782 /// See @ref HAPI_Sessions for more on sessions.
2783 /// Pass NULL to just use the default in-process session.
2784 /// <!-- default NULL -->
2785 ///
2786 /// @param[in] node_id
2787 /// The node id.
2788 ///
2789 /// @param[in] parm_id
2790 /// The parm id.
2791 ///
2792 /// @param[in] tag_index
2793 /// The tag index, which should be between 0 and
2794 /// ::HAPI_ParmInfo::tagCount - 1.
2795 /// @note These indices are invalidated whenever tags are added
2796 /// to parameters. Do not store these or expect them to be the
2797 /// same if the scene is modified.
2798 /// <!-- min 0 -->
2799 /// <!-- max ::HAPI_ParmInfo::tagCount - 1 -->
2800 ///
2801 /// @param[out] tag_name
2802 /// The returned tag name. This string handle will be valid
2803 /// until another call to ::HAPI_GetParmTagName().
2804 ///
2805 HAPI_DECL HAPI_GetParmTagName( const HAPI_Session * session,
2806  HAPI_NodeId node_id,
2807  HAPI_ParmId parm_id,
2808  int tag_index,
2809  HAPI_StringHandle * tag_name );
2810 
2811 /// @brief Get the tag value on a parameter given the tag name.
2812 ///
2813 /// @ingroup Parms
2814 ///
2815 /// @param[in] session
2816 /// The session of Houdini you are interacting with.
2817 /// See @ref HAPI_Sessions for more on sessions.
2818 /// Pass NULL to just use the default in-process session.
2819 /// <!-- default NULL -->
2820 ///
2821 /// @param[in] node_id
2822 /// The node id.
2823 ///
2824 /// @param[in] parm_id
2825 /// The parm id.
2826 ///
2827 /// @param[in] tag_name
2828 /// The tag name, either known or returned by
2829 /// ::HAPI_GetParmTagName().
2830 ///
2831 /// @param[out] tag_value
2832 /// The returned tag value. This string handle will be valid
2833 /// until another call to ::HAPI_GetParmTagValue().
2834 ///
2836  HAPI_NodeId node_id,
2837  HAPI_ParmId parm_id,
2838  const char * tag_name,
2839  HAPI_StringHandle * tag_value );
2840 
2841 /// @brief See if a parameter has a specific tag.
2842 ///
2843 /// @ingroup Parms
2844 ///
2845 /// @param[in] session
2846 /// The session of Houdini you are interacting with.
2847 /// See @ref HAPI_Sessions for more on sessions.
2848 /// Pass NULL to just use the default in-process session.
2849 /// <!-- default NULL -->
2850 ///
2851 /// @param[in] node_id
2852 /// The node id.
2853 ///
2854 /// @param[in] parm_id
2855 /// The parm id.
2856 ///
2857 /// @param[in] tag_name
2858 /// The tag name to look for.
2859 ///
2860 /// @param[out] has_tag
2861 /// True if the tag exists on the parameter, false otherwise.
2862 ///
2863 HAPI_DECL HAPI_ParmHasTag( const HAPI_Session * session,
2864  HAPI_NodeId node_id,
2865  HAPI_ParmId parm_id,
2866  const char * tag_name,
2867  HAPI_Bool * has_tag );
2868 
2869 /// @brief See if a parameter has an expression
2870 ///
2871 /// @ingroup Parms
2872 ///
2873 /// @param[in] session
2874 /// The session of Houdini you are interacting with.
2875 /// See @ref HAPI_Sessions for more on sessions.
2876 /// Pass NULL to just use the default in-process session.
2877 /// <!-- default NULL -->
2878 ///
2879 /// @param[in] node_id
2880 /// The node id.
2881 ///
2882 /// @param[in] parm_name
2883 /// The parm name.
2884 ///
2885 /// @param[in] index
2886 /// The parm index.
2887 ///
2888 /// @param[out] has_expression
2889 /// True if an expression exists on the parameter, false otherwise.
2890 ///
2892  HAPI_NodeId node_id,
2893  const char * parm_name,
2894  int index,
2895  HAPI_Bool * has_expression );
2896 
2897 /// @brief Get the first parm with a specific, ideally unique, tag on it.
2898 /// This is particularly useful for getting the ogl parameters on a
2899 /// material node.
2900 ///
2901 /// @ingroup Parms
2902 ///
2903 /// @param[in] session
2904 /// The session of Houdini you are interacting with.
2905 /// See @ref HAPI_Sessions for more on sessions.
2906 /// Pass NULL to just use the default in-process session.
2907 /// <!-- default NULL -->
2908 ///
2909 /// @param[in] node_id
2910 /// The node id.
2911 ///
2912 /// @param[in] tag_name
2913 /// The tag name to look for.
2914 ///
2915 /// @param[out] parm_id
2916 /// The returned parm id. This will be -1 if no parm was found
2917 /// with this tag.
2918 ///
2919 HAPI_DECL HAPI_GetParmWithTag( const HAPI_Session * session,
2920  HAPI_NodeId node_id,
2921  const char * tag_name,
2922  HAPI_ParmId * parm_id );
2923 
2924 /// @brief Get single integer or float parm expression by name
2925 /// or Null string if no expression is present
2926 ///
2927 /// @ingroup Parms
2928 ///
2929 /// @param[in] session
2930 /// The session of Houdini you are interacting with.
2931 /// See @ref HAPI_Sessions for more on sessions.
2932 /// Pass NULL to just use the default in-process session.
2933 /// <!-- default NULL -->
2934 ///
2935 /// @param[in] node_id
2936 /// The node id.
2937 ///
2938 /// @param[in] parm_name
2939 /// The parm name.
2940 ///
2941 /// @param[in] index
2942 /// Index within the parameter's values tuple.
2943 ///
2944 /// @param[out] value
2945 /// The returned string value.
2946 ///
2948  HAPI_NodeId node_id,
2949  const char * parm_name,
2950  int index,
2951  HAPI_StringHandle * value );
2952 
2953 /// @brief Revert single parm by name to default
2954 ///
2955 /// @ingroup Parms
2956 ///
2957 /// @param[in] session
2958 /// The session of Houdini you are interacting with.
2959 /// See @ref HAPI_Sessions for more on sessions.
2960 /// Pass NULL to just use the default in-process session.
2961 /// <!-- default NULL -->
2962 ///
2963 /// @param[in] node_id
2964 /// The node id.
2965 ///
2966 /// @param[in] parm_name
2967 /// The parm name.
2968 ///
2969 /// @param[in] index
2970 /// Index within the parameter's values tuple.
2971 ///
2973  HAPI_NodeId node_id,
2974  const char * parm_name,
2975  int index );
2976 
2977 /// @brief Revert all instances of the parm by name to defaults
2978 ///
2979 /// @ingroup Parms
2980 ///
2981 /// @param[in] session
2982 /// The session of Houdini you are interacting with.
2983 /// See @ref HAPI_Sessions for more on sessions.
2984 /// Pass NULL to just use the default in-process session.
2985 /// <!-- default NULL -->
2986 ///
2987 /// @param[in] node_id
2988 /// The node id.
2989 ///
2990 /// @param[in] parm_name
2991 /// The parm name.
2992 ///
2994  HAPI_NodeId node_id,
2995  const char * parm_name );
2996 
2997 /// @brief Set (push) an expression string. We can only set a single value at
2998 /// a time because we want to avoid fixed size string buffers.
2999 ///
3000 /// @note Regardless of the value, when calling this function
3001 /// on a parameter, if that parameter has a callback function
3002 /// attached to it, that callback function will be called. For
3003 /// example, if the parameter is a button the button will be
3004 /// pressed.
3005 ///
3006 /// @note In threaded mode, this is an _async call_!
3007 ///
3008 /// This API will invoke the cooking thread if threading is
3009 /// enabled. This means it will return immediately. Use
3010 /// the status and cooking count APIs under DIAGNOSTICS to get
3011 /// a sense of the progress. All other API calls will block
3012 /// until the cook operation has finished.
3013 ///
3014 /// Also note that the cook result won't be of type
3015 /// ::HAPI_STATUS_CALL_RESULT like all calls (including this one).
3016 /// Whenever the threading cook is done it will fill the
3017 /// @a cook result which is queried using
3018 /// ::HAPI_STATUS_COOK_RESULT.
3019 ///
3020 /// @ingroup Parms
3021 ///
3022 /// @param[in] session
3023 /// The session of Houdini you are interacting with.
3024 /// See @ref HAPI_Sessions for more on sessions.
3025 /// Pass NULL to just use the default in-process session.
3026 /// <!-- default NULL -->
3027 ///
3028 /// @param[in] node_id
3029 /// The node id.
3030 ///
3031 /// @param[in] value
3032 /// The expression string.
3033 ///
3034 /// @param[in] parm_id
3035 /// Parameter id of the parameter being updated.
3036 ///
3037 /// @param[in] index
3038 /// Index within the parameter's values tuple.
3039 ///
3041  HAPI_NodeId node_id,
3042  const char * value,
3043  HAPI_ParmId parm_id, int index );
3044 
3045 /// @brief Remove the expression string, leaving the value of the
3046 /// parm at the current value of the expression
3047 ///
3048 /// @note Regardless of the value, when calling this function
3049 /// on a parameter, if that parameter has a callback function
3050 /// attached to it, that callback function will be called. For
3051 /// example, if the parameter is a button the button will be
3052 /// pressed.
3053 ///
3054 /// @note In threaded mode, this is an _async call_!
3055 ///
3056 /// This API will invoke the cooking thread if threading is
3057 /// enabled. This means it will return immediately. Use
3058 /// the status and cooking count APIs under DIAGNOSTICS to get
3059 /// a sense of the progress. All other API calls will block
3060 /// until the cook operation has finished.
3061 ///
3062 /// Also note that the cook result won't be of type
3063 /// ::HAPI_STATUS_CALL_RESULT like all calls (including this one).
3064 /// Whenever the threading cook is done it will fill the
3065 /// @a cook result which is queried using
3066 /// ::HAPI_STATUS_COOK_RESULT.
3067 ///
3068 /// @ingroup Parms
3069 ///
3070 /// @param[in] session
3071 /// The session of Houdini you are interacting with.
3072 /// See @ref HAPI_Sessions for more on sessions.
3073 /// Pass NULL to just use the default in-process session.
3074 /// <!-- default NULL -->
3075 ///
3076 /// @param[in] node_id
3077 /// The node id.
3078 ///
3079 /// @param[in] parm_id
3080 /// Parameter id of the parameter being updated.
3081 ///
3082 /// @param[in] index
3083 /// Index within the parameter's values tuple.
3084 ///
3086  HAPI_NodeId node_id,
3087  HAPI_ParmId parm_id, int index );
3088 
3089 /// @brief Get single parm int value by name.
3090 ///
3091 /// @ingroup Parms
3092 ///
3093 /// @param[in] session
3094 /// The session of Houdini you are interacting with.
3095 /// See @ref HAPI_Sessions for more on sessions.
3096 /// Pass NULL to just use the default in-process session.
3097 /// <!-- default NULL -->
3098 ///
3099 /// @param[in] node_id
3100 /// The node id.
3101 ///
3102 /// @param[in] parm_name
3103 /// The parm name.
3104 ///
3105 /// @param[in] index
3106 /// Index within the parameter's values tuple.
3107 ///
3108 /// @param[out] value
3109 /// The returned int value.
3110 ///
3112  HAPI_NodeId node_id,
3113  const char * parm_name,
3114  int index,
3115  int * value );
3116 
3117 /// @brief Fill an array of parameter int values. This is more efficient
3118 /// than calling ::HAPI_GetParmIntValue() individually for each
3119 /// parameter value.
3120 ///
3121 /// @ingroup Parms
3122 ///
3123 /// @param[in] session
3124 /// The session of Houdini you are interacting with.
3125 /// See @ref HAPI_Sessions for more on sessions.
3126 /// Pass NULL to just use the default in-process session.
3127 /// <!-- default NULL -->
3128 ///
3129 /// @param[in] node_id
3130 /// The node id.
3131 ///
3132 /// @param[out] values_array
3133 /// Array of ints at least the size of length.
3134 ///
3135 /// @param[in] start
3136 /// First index of range. Must be at least 0 and at
3137 /// most ::HAPI_NodeInfo::parmIntValueCount - 1.
3138 /// <!-- min 0 -->
3139 /// <!-- max ::HAPI_NodeInfo::parmIntValueCount - 1 -->
3140 /// <!-- default 0 -->
3141 ///
3142 /// @param[in] length
3143 /// Must be at least 1 and at most
3144 /// ::HAPI_NodeInfo::parmIntValueCount - start.
3145 /// <!-- min 1 -->
3146 /// <!-- max ::HAPI_NodeInfo::parmIntValueCount - start -->
3147 /// <!-- source ::HAPI_NodeInfo::parmIntValueCount - start -->
3148 ///
3150  HAPI_NodeId node_id,
3151  int * values_array,
3152  int start, int length );
3153 
3154 /// @brief Get single parm float value by name.
3155 ///
3156 /// @ingroup Parms
3157 ///
3158 /// @param[in] session
3159 /// The session of Houdini you are interacting with.
3160 /// See @ref HAPI_Sessions for more on sessions.
3161 /// Pass NULL to just use the default in-process session.
3162 /// <!-- default NULL -->
3163 ///
3164 /// @param[in] node_id
3165 /// The node id.
3166 ///
3167 /// @param[in] parm_name
3168 /// The parm name.
3169 ///
3170 /// @param[in] index
3171 /// Index within the parameter's values tuple.
3172 ///
3173 /// @param[out] value
3174 /// The returned float value.
3175 ///
3177  HAPI_NodeId node_id,
3178  const char * parm_name,
3179  int index,
3180  float * value );
3181 
3182 /// @brief Fill an array of parameter float values. This is more efficient
3183 /// than calling ::HAPI_GetParmFloatValue() individually for each
3184 /// parameter value.
3185 ///
3186 /// @ingroup Parms
3187 ///
3188 /// @param[in] session
3189 /// The session of Houdini you are interacting with.
3190 /// See @ref HAPI_Sessions for more on sessions.
3191 /// Pass NULL to just use the default in-process session.
3192 /// <!-- default NULL -->
3193 ///
3194 /// @param[in] node_id
3195 /// The node id.
3196 ///
3197 /// @param[out] values_array
3198 /// Array of floats at least the size of length.
3199 ///
3200 /// @param[in] start
3201 /// First index of range. Must be at least 0 and at
3202 /// most ::HAPI_NodeInfo::parmFloatValueCount - 1.
3203 /// <!-- min 0 -->
3204 /// <!-- max ::HAPI_NodeInfo::parmFloatValueCount - 1 -->
3205 /// <!-- default 0 -->
3206 ///
3207 /// @param[in] length
3208 /// Must be at least 1 and at most
3209 /// ::HAPI_NodeInfo::parmFloatValueCount - start.
3210 /// <!-- min 1 -->
3211 /// <!-- max ::HAPI_NodeInfo::parmFloatValueCount - start -->
3212 /// <!-- source ::HAPI_NodeInfo::parmFloatValueCount - start -->
3213 ///
3215  HAPI_NodeId node_id,
3216  float * values_array,
3217  int start, int length );
3218 
3219 /// @brief Get single parm string value by name.
3220 ///
3221 /// @ingroup Parms
3222 ///
3223 /// @param[in] session
3224 /// The session of Houdini you are interacting with.
3225 /// See @ref HAPI_Sessions for more on sessions.
3226 /// Pass NULL to just use the default in-process session.
3227 /// <!-- default NULL -->
3228 ///
3229 /// @param[in] node_id
3230 /// The node id.
3231 ///
3232 /// @param[in] parm_name
3233 /// The name of the parameter.
3234 ///
3235 /// @param[in] index
3236 /// Index within the parameter's values tuple.
3237 ///
3238 /// @param[in] evaluate
3239 /// Whether or not to evaluate the string expression.
3240 /// For example, the string "$F" would evaluate to the
3241 /// current frame number. So, passing in evaluate = false
3242 /// would give you back the string "$F" and passing
3243 /// in evaluate = true would give you back "1" (assuming
3244 /// the current frame is 1).
3245 /// <!-- default true -->
3246 ///
3247 /// @param[out] value
3248 /// The returned string value.
3249 ///
3251  HAPI_NodeId node_id,
3252  const char * parm_name,
3253  int index,
3254  HAPI_Bool evaluate,
3255  HAPI_StringHandle * value );
3256 
3257 /// @brief Fill an array of parameter string handles. These handles must
3258 /// be used in conjunction with ::HAPI_GetString() to get the
3259 /// actual string values. This is more efficient than calling
3260 /// ::HAPI_GetParmStringValue() individually for each
3261 /// parameter value.
3262 ///
3263 /// @ingroup Parms
3264 ///
3265 /// @param[in] session
3266 /// The session of Houdini you are interacting with.
3267 /// See @ref HAPI_Sessions for more on sessions.
3268 /// Pass NULL to just use the default in-process session.
3269 /// <!-- default NULL -->
3270 ///
3271 /// @param[in] node_id
3272 /// The node id.
3273 ///
3274 /// @param[in] evaluate
3275 /// Whether or not to evaluate the string expression.
3276 /// For example, the string "$F" would evaluate to the
3277 /// current frame number. So, passing in evaluate = false
3278 /// would give you back the string "$F" and passing
3279 /// in evaluate = true would give you back "1" (assuming
3280 /// the current frame is 1).
3281 ///
3282 /// @param[out] values_array
3283 /// Array of integers at least the size of length.
3284 ///
3285 /// @param[in] start
3286 /// First index of range. Must be at least 0 and at
3287 /// most ::HAPI_NodeInfo::parmStringValueCount - 1.
3288 /// <!-- min 0 -->
3289 /// <!-- max ::HAPI_NodeInfo::parmStringValueCount - 1 -->
3290 /// <!-- default 0 -->
3291 ///
3292 /// @param[in] length
3293 /// Must be at least 1 and at most
3294 /// ::HAPI_NodeInfo::parmStringValueCount - start.
3295 /// <!-- min 1 -->
3296 /// <!-- max ::HAPI_NodeInfo::parmStringValueCount - start -->
3297 /// <!-- source ::HAPI_NodeInfo::parmStringValueCount - start -->
3298 ///
3300  HAPI_NodeId node_id,
3301  HAPI_Bool evaluate,
3302  HAPI_StringHandle * values_array,
3303  int start, int length );
3304 
3305 /// @brief Get a single node id parm value of an Op Path parameter. This is
3306 /// how you see which node is connected as an input for the current
3307 /// node (via parameter).
3308 ///
3309 /// @ingroup Parms
3310 ///
3311 /// @param[in] session
3312 /// The session of Houdini you are interacting with.
3313 /// See @ref HAPI_Sessions for more on sessions.
3314 /// Pass NULL to just use the default in-process session.
3315 /// <!-- default NULL -->
3316 ///
3317 /// @param[in] node_id
3318 /// The node id.
3319 ///
3320 /// @param[in] parm_name
3321 /// The name of the parameter.
3322 ///
3323 /// @param[out] value
3324 /// The node id of the node being pointed to by the parm.
3325 /// If there is no node found, -1 will be returned.
3326 ///
3328  HAPI_NodeId node_id,
3329  const char * parm_name,
3330  HAPI_NodeId * value );
3331 
3332 /// @brief Extract a file specified by path on a parameter. This will copy
3333 /// the file to the destination directory from wherever it might be,
3334 /// inlcuding inside the asset definition or online.
3335 ///
3336 /// @ingroup Parms
3337 ///
3338 /// @param[in] session
3339 /// The session of Houdini you are interacting with.
3340 /// See @ref HAPI_Sessions for more on sessions.
3341 /// Pass NULL to just use the default in-process session.
3342 /// <!-- default NULL -->
3343 ///
3344 /// @param[in] node_id
3345 /// The node id.
3346 ///
3347 /// @param[in] parm_name
3348 /// The name of the parameter.
3349 ///
3350 /// @param[in] destination_directory
3351 /// The destination directory to copy the file to.
3352 ///
3353 /// @param[in] destination_file_name
3354 /// The destination file name.
3355 ///
3356 HAPI_DECL HAPI_GetParmFile( const HAPI_Session * session,
3357  HAPI_NodeId node_id,
3358  const char * parm_name,
3359  const char * destination_directory,
3360  const char * destination_file_name );
3361 
3362 /// @brief Fill an array of ::HAPI_ParmChoiceInfo structs with parameter
3363 /// choice list information from the asset instance node.
3364 ///
3365 /// @ingroup Parms
3366 ///
3367 /// @param[in] session
3368 /// The session of Houdini you are interacting with.
3369 /// See @ref HAPI_Sessions for more on sessions.
3370 /// Pass NULL to just use the default in-process session.
3371 /// <!-- default NULL -->
3372 ///
3373 /// @param[in] node_id
3374 /// The node id.
3375 ///
3376 /// @param[out] parm_choices_array
3377 /// Array of ::HAPI_ParmChoiceInfo exactly the size of
3378 /// length.
3379 ///
3380 /// @param[in] start
3381 /// First index of range. Must be at least 0 and at
3382 /// most ::HAPI_NodeInfo::parmChoiceCount - 1.
3383 /// <!-- min 0 -->
3384 /// <!-- max ::HAPI_NodeInfo::parmChoiceCount - 1 -->
3385 /// <!-- default 0 -->
3386 ///
3387 /// @param[in] length
3388 /// Must be at least 1 and at most
3389 /// ::HAPI_NodeInfo::parmChoiceCount - start.
3390 /// <!-- min 1 -->
3391 /// <!-- max ::HAPI_NodeInfo::parmChoiceCount - start -->
3392 /// <!-- source ::HAPI_NodeInfo::parmChoiceCount - start -->
3393 ///
3395  HAPI_NodeId node_id,
3396  HAPI_ParmChoiceInfo * parm_choices_array,
3397  int start, int length );
3398 
3399 /// @brief Set single parm int value by name.
3400 ///
3401 /// @note Regardless of the value, when calling this function
3402 /// on a parameter, if that parameter has a callback function
3403 /// attached to it, that callback function will be called. For
3404 /// example, if the parameter is a button the button will be
3405 /// pressed.
3406 ///
3407 /// @note In threaded mode, this is an _async call_!
3408 ///
3409 /// This API will invoke the cooking thread if threading is
3410 /// enabled. This means it will return immediately. Use
3411 /// the status and cooking count APIs under DIAGNOSTICS to get
3412 /// a sense of the progress. All other API calls will block
3413 /// until the cook operation has finished.
3414 ///
3415 /// Also note that the cook result won't be of type
3416 /// ::HAPI_STATUS_CALL_RESULT like all calls (including this one).
3417 /// Whenever the threading cook is done it will fill the
3418 /// @a cook result which is queried using
3419 /// ::HAPI_STATUS_COOK_RESULT.
3420 ///
3421 /// @ingroup Parms
3422 ///
3423 /// @param[in] session
3424 /// The session of Houdini you are interacting with.
3425 /// See @ref HAPI_Sessions for more on sessions.
3426 /// Pass NULL to just use the default in-process session.
3427 /// <!-- default NULL -->
3428 ///
3429 /// @param[in] node_id
3430 /// The node id.
3431 ///
3432 /// @param[in] parm_name
3433 /// The parm name.
3434 ///
3435 /// @param[in] index
3436 /// Index within the parameter's values tuple.
3437 ///
3438 /// @param[in] value
3439 /// The int value.
3440 ///
3442  HAPI_NodeId node_id,
3443  const char * parm_name,
3444  int index,
3445  int value );
3446 
3447 /// @brief Set (push) an array of parameter int values.
3448 ///
3449 /// @note Regardless of the values, when calling this function
3450 /// on a set of parameters, if any parameter has a callback
3451 /// function attached to it, that callback function will be called.
3452 /// For example, if the parameter is a button the button will be
3453 /// pressed.
3454 ///
3455 /// @note In threaded mode, this is an _async call_!
3456 ///
3457 /// This API will invoke the cooking thread if threading is
3458 /// enabled. This means it will return immediately. Use
3459 /// the status and cooking count APIs under DIAGNOSTICS to get
3460 /// a sense of the progress. All other API calls will block
3461 /// until the cook operation has finished.
3462 ///
3463 /// Also note that the cook result won't be of type
3464 /// ::HAPI_STATUS_CALL_RESULT like all calls (including this one).
3465 /// Whenever the threading cook is done it will fill the
3466 /// @a cook result which is queried using
3467 /// ::HAPI_STATUS_COOK_RESULT.
3468 ///
3469 /// @ingroup Parms
3470 ///
3471 /// @param[in] session
3472 /// The session of Houdini you are interacting with.
3473 /// See @ref HAPI_Sessions for more on sessions.
3474 /// Pass NULL to just use the default in-process session.
3475 /// <!-- default NULL -->
3476 ///
3477 /// @param[in] node_id
3478 /// The node id.
3479 ///
3480 /// @param[in] values_array
3481 /// Array of integers at least the size of length.
3482 /// <!-- min length -->
3483 ///
3484 /// @param[in] start
3485 /// First index of range. Must be at least 0 and at
3486 /// most ::HAPI_NodeInfo::parmIntValueCount - 1.
3487 /// <!-- min 0 -->
3488 /// <!-- max ::HAPI_NodeInfo::parmIntValueCount - 1 -->
3489 /// <!-- default 0 -->
3490 ///
3491 /// @param[in] length
3492 /// Must be at least 1 and at most
3493 /// ::HAPI_NodeInfo::parmIntValueCount - start.
3494 /// <!-- min 1 -->
3495 /// <!-- max ::HAPI_NodeInfo::parmIntValueCount - start -->
3496 /// <!-- source ::HAPI_NodeInfo::parmIntValueCount - start -->
3497 ///
3499  HAPI_NodeId node_id,
3500  const int * values_array,
3501  int start, int length );
3502 
3503 /// @brief Set single parm float value by name.
3504 ///
3505 /// @note Regardless of the value, when calling this function
3506 /// on a parameter, if that parameter has a callback function
3507 /// attached to it, that callback function will be called. For
3508 /// example, if the parameter is a button the button will be
3509 /// pressed.
3510 ///
3511 /// @note In threaded mode, this is an _async call_!
3512 ///
3513 /// This API will invoke the cooking thread if threading is
3514 /// enabled. This means it will return immediately. Use
3515 /// the status and cooking count APIs under DIAGNOSTICS to get
3516 /// a sense of the progress. All other API calls will block
3517 /// until the cook operation has finished.
3518 ///
3519 /// Also note that the cook result won't be of type
3520 /// ::HAPI_STATUS_CALL_RESULT like all calls (including this one).
3521 /// Whenever the threading cook is done it will fill the
3522 /// @a cook result which is queried using
3523 /// ::HAPI_STATUS_COOK_RESULT.
3524 ///
3525 /// @ingroup Parms
3526 ///
3527 /// @param[in] session
3528 /// The session of Houdini you are interacting with.
3529 /// See @ref HAPI_Sessions for more on sessions.
3530 /// Pass NULL to just use the default in-process session.
3531 /// <!-- default NULL -->
3532 ///
3533 /// @param[in] node_id
3534 /// The node id.
3535 ///
3536 /// @param[in] parm_name
3537 /// The parm name.
3538 ///
3539 /// @param[in] index
3540 /// Index within the parameter's values tuple.
3541 ///
3542 /// @param[in] value
3543 /// The float value.
3544 ///
3546  HAPI_NodeId node_id,
3547  const char * parm_name,
3548  int index,
3549  float value );
3550 
3551 /// @brief Set (push) an array of parameter float values.
3552 ///
3553 /// @note Regardless of the values, when calling this function
3554 /// on a set of parameters, if any parameter has a callback
3555 /// function attached to it, that callback function will be called.
3556 /// For example, if the parameter is a button the button will be
3557 /// pressed.
3558 ///
3559 /// @note In threaded mode, this is an _async call_!
3560 ///
3561 /// This API will invoke the cooking thread if threading is
3562 /// enabled. This means it will return immediately. Use
3563 /// the status and cooking count APIs under DIAGNOSTICS to get
3564 /// a sense of the progress. All other API calls will block
3565 /// until the cook operation has finished.
3566 ///
3567 /// Also note that the cook result won't be of type
3568 /// ::HAPI_STATUS_CALL_RESULT like all calls (including this one).
3569 /// Whenever the threading cook is done it will fill the
3570 /// @a cook result which is queried using
3571 /// ::HAPI_STATUS_COOK_RESULT.
3572 ///
3573 /// @ingroup Parms
3574 ///
3575 /// @param[in] session
3576 /// The session of Houdini you are interacting with.
3577 /// See @ref HAPI_Sessions for more on sessions.
3578 /// Pass NULL to just use the default in-process session.
3579 /// <!-- default NULL -->
3580 ///
3581 /// @param[in] node_id
3582 /// The node id.
3583 ///
3584 /// @param[in] values_array
3585 /// Array of floats at least the size of length.
3586 ///
3587 /// @param[in] start
3588 /// First index of range. Must be at least 0 and at
3589 /// most ::HAPI_NodeInfo::parmFloatValueCount - 1.
3590 ///
3591 /// @param[in] length
3592 /// Must be at least 1 and at most
3593 /// ::HAPI_NodeInfo::parmFloatValueCount - start.
3594 ///
3596  HAPI_NodeId node_id,
3597  const float * values_array,
3598  int start, int length );
3599 
3600 /// @brief Set (push) a string value. We can only set a single value at
3601 /// a time because we want to avoid fixed size string buffers.
3602 ///
3603 /// @note Regardless of the value, when calling this function
3604 /// on a parameter, if that parameter has a callback function
3605 /// attached to it, that callback function will be called. For
3606 /// example, if the parameter is a button the button will be
3607 /// pressed.
3608 ///
3609 /// @note In threaded mode, this is an _async call_!
3610 ///
3611 /// This API will invoke the cooking thread if threading is
3612 /// enabled. This means it will return immediately. Use
3613 /// the status and cooking count APIs under DIAGNOSTICS to get
3614 /// a sense of the progress. All other API calls will block
3615 /// until the cook operation has finished.
3616 ///
3617 /// Also note that the cook result won't be of type
3618 /// ::HAPI_STATUS_CALL_RESULT like all calls (including this one).
3619 /// Whenever the threading cook is done it will fill the
3620 /// @a cook result which is queried using
3621 /// ::HAPI_STATUS_COOK_RESULT.
3622 ///
3623 /// @ingroup Parms
3624 ///
3625 /// @param[in] session
3626 /// The session of Houdini you are interacting with.
3627 /// See @ref HAPI_Sessions for more on sessions.
3628 /// Pass NULL to just use the default in-process session.
3629 /// <!-- default NULL -->
3630 ///
3631 /// @param[in] node_id
3632 /// The node id.
3633 ///
3634 /// @param[in] value
3635 /// The string value.
3636 ///
3637 /// @param[in] parm_id
3638 /// Parameter id of the parameter being updated.
3639 ///
3640 /// @param[in] index
3641 /// Index within the parameter's values tuple.
3642 ///
3644  HAPI_NodeId node_id,
3645  const char * value,
3646  HAPI_ParmId parm_id, int index );
3647 
3648 /// @brief Set a node id parm value of an Op Path parameter. For example,
3649 /// This is how you connect the geometry output of an asset to the
3650 /// geometry input of another asset - whether the input is a parameter
3651 /// or a node input (the top of the node). Node inputs get converted
3652 /// top parameters in HAPI.
3653 ///
3654 /// @ingroup Parms
3655 ///
3656 /// @param[in] session
3657 /// The session of Houdini you are interacting with.
3658 /// See @ref HAPI_Sessions for more on sessions.
3659 /// Pass NULL to just use the default in-process session.
3660 /// <!-- default NULL -->
3661 ///
3662 /// @param[in] node_id
3663 /// The node id.
3664 ///
3665 /// @param[in] parm_name
3666 /// The name of the parameter.
3667 ///
3668 /// @param[in] value
3669 /// The node id of the node being connected. Pass -1 to
3670 /// disconnect.
3671 ///
3673  HAPI_NodeId node_id,
3674  const char * parm_name,
3675  HAPI_NodeId value );
3676 
3677 /// @brief Insert an instance of a multiparm before instance_position.
3678 ///
3679 /// @ingroup Parms
3680 ///
3681 /// @param[in] session
3682 /// The session of Houdini you are interacting with.
3683 /// See @ref HAPI_Sessions for more on sessions.
3684 /// Pass NULL to just use the default in-process session.
3685 /// <!-- default NULL -->
3686 ///
3687 /// @param[in] node_id
3688 /// The node id.
3689 ///
3690 /// @param[in] parm_id
3691 /// A parm id given by a ::HAPI_ParmInfo struct that
3692 /// has type ::HAPI_PARMTYPE_MULTIPARMLIST.
3693 ///
3694 /// @param[in] instance_position
3695 /// The new instance will be inserted at this position
3696 /// index. Do note the multiparms can start at position
3697 /// 1 or 0. Use ::HAPI_ParmInfo::instanceStartOffset to
3698 /// distinguish.
3699 ///
3701  HAPI_NodeId node_id,
3702  HAPI_ParmId parm_id,
3703  int instance_position );
3704 
3705 /// @brief Remove the instance of a multiparm given by instance_position.
3706 ///
3707 /// @ingroup Parms
3708 ///
3709 /// @param[in] session
3710 /// The session of Houdini you are interacting with.
3711 /// See @ref HAPI_Sessions for more on sessions.
3712 /// Pass NULL to just use the default in-process session.
3713 /// <!-- default NULL -->
3714 ///
3715 /// @param[in] node_id
3716 /// The node id.
3717 ///
3718 /// @param[in] parm_id
3719 /// A parm id given by a ::HAPI_ParmInfo struct that
3720 /// has type ::HAPI_PARMTYPE_MULTIPARMLIST.
3721 ///
3722 /// @param[in] instance_position
3723 /// The instance at instance_position will removed.
3724 ///
3726  HAPI_NodeId node_id,
3727  HAPI_ParmId parm_id,
3728  int instance_position );
3729 
3730 // HANDLES ------------------------------------------------------------------
3731 
3732 /// @brief Fill an array of ::HAPI_HandleInfo structs with information
3733 /// about every exposed user manipulation handle on the node.
3734 ///
3735 /// @ingroup Parms
3736 ///
3737 /// @param[in] session
3738 /// The session of Houdini you are interacting with.
3739 /// See @ref HAPI_Sessions for more on sessions.
3740 /// Pass NULL to just use the default in-process session.
3741 /// <!-- default NULL -->
3742 ///
3743 /// @param[in] node_id
3744 /// The node id.
3745 ///
3746 /// @param[out] handle_infos_array
3747 /// Array of ::HAPI_HandleInfo at least the size of length.
3748 ///
3749 /// @param[in] start
3750 /// First index of range. Must be at least 0 and at
3751 /// most ::HAPI_AssetInfo::handleCount - 1.
3752 /// <!-- default 0 -->
3753 ///
3754 /// @param[in] length
3755 /// Must be at least 1 and at most
3756 /// ::HAPI_AssetInfo::handleCount - start.
3757 /// <!-- source ::HAPI_AssetInfo::handleCount - start -->
3758 ///
3759 HAPI_DECL HAPI_GetHandleInfo( const HAPI_Session * session,
3760  HAPI_NodeId node_id,
3761  HAPI_HandleInfo * handle_infos_array,
3762  int start, int length );
3763 
3764 /// @brief Fill an array of ::HAPI_HandleBindingInfo structs with information
3765 /// about the binding of a particular handle on the given node.
3766 ///
3767 /// @ingroup Parms
3768 ///
3769 /// @param[in] session
3770 /// The session of Houdini you are interacting with.
3771 /// See @ref HAPI_Sessions for more on sessions.
3772 /// Pass NULL to just use the default in-process session.
3773 /// <!-- default NULL -->
3774 ///
3775 /// @param[in] node_id
3776 /// The node id.
3777 ///
3778 /// @param[in] handle_index
3779 /// The index of the handle, from 0 to handleCount - 1
3780 /// from the call to ::HAPI_GetAssetInfo().
3781 ///
3782 /// @param[out] handle_binding_infos_array
3783 /// Array of ::HAPI_HandleBindingInfo at least the size
3784 /// of length.
3785 ///
3786 /// @param[in] start
3787 /// First index of range. Must be at least 0 and at
3788 /// most ::HAPI_HandleInfo::bindingsCount - 1.
3789 /// <!-- default 0 -->
3790 ///
3791 /// @param[in] length
3792 /// Must be at least 1 and at most
3793 /// ::HAPI_HandleInfo::bindingsCount - start.
3794 /// <!-- source ::HAPI_AssetInfo::bindingsCount - start -->
3795 ///
3797  const HAPI_Session * session,
3798  HAPI_NodeId node_id,
3799  int handle_index,
3800  HAPI_HandleBindingInfo * handle_binding_infos_array,
3801  int start, int length );
3802 
3803 /// @defgroup Presets Presets
3804 /// Functions for working with Node presets
3805 
3806 /// @brief Generate a preset blob of the current state of all the
3807 /// parameter values, cache it, and return its size in bytes.
3808 ///
3809 /// @ingroup Presets
3810 ///
3811 /// @param[in] session
3812 /// The session of Houdini you are interacting with.
3813 /// See @ref HAPI_Sessions for more on sessions.
3814 /// Pass NULL to just use the default in-process session.
3815 /// <!-- default NULL -->
3816 ///
3817 /// @param[in] node_id
3818 /// The exposed node id.
3819 ///
3820 /// @param[in] preset_type
3821 /// The preset type.
3822 ///
3823 /// @param[in] preset_name
3824 /// Optional. This is only used if the @p preset_type is
3825 /// ::HAPI_PRESETTYPE_IDX. If NULL is given, the preset
3826 /// name will be the same as the name of the node with
3827 /// the given @p node_id.
3828 ///
3829 /// @param[out] buffer_length
3830 /// Size of the buffer.
3831 ///
3833  HAPI_NodeId node_id,
3834  HAPI_PresetType preset_type,
3835  const char * preset_name,
3836  int * buffer_length );
3837 
3838 /// @brief Generates a preset for the given asset.
3839 ///
3840 /// @ingroup Presets
3841 ///
3842 /// @param[in] session
3843 /// The session of Houdini you are interacting with.
3844 /// See @ref HAPI_Sessions for more on sessions.
3845 /// Pass NULL to just use the default in-process session.
3846 /// <!-- default NULL -->
3847 ///
3848 /// @param[in] node_id
3849 /// The exposed node id.
3850 ///
3851 /// @param[out] buffer
3852 /// Buffer to hold the preset data.
3853 ///
3854 /// @param[in] buffer_length
3855 /// Size of the buffer. Should be the same as the length
3856 /// returned by ::HAPI_GetPresetBufLength().
3857 ///
3858 HAPI_DECL HAPI_GetPreset( const HAPI_Session * session,
3859  HAPI_NodeId node_id,
3860  char * buffer,
3861  int buffer_length );
3862 
3863 /// @brief Sets a particular asset to a given preset.
3864 ///
3865 /// @ingroup Presets
3866 ///
3867 /// @param[in] session
3868 /// The session of Houdini you are interacting with.
3869 /// See @ref HAPI_Sessions for more on sessions.
3870 /// Pass NULL to just use the default in-process session.
3871 /// <!-- default NULL -->
3872 ///
3873 /// @param[in] node_id
3874 /// The exposed node id.
3875 ///
3876 /// @param[in] preset_type
3877 /// The preset type.
3878 ///
3879 /// @param[in] preset_name
3880 /// Optional. This is only used if the @p preset_type is
3881 /// ::HAPI_PRESETTYPE_IDX. If NULL is give, the first
3882 /// preset in the IDX file will be chosen.
3883 /// <!-- default NULL -->
3884 ///
3885 /// @param[in] buffer
3886 /// Buffer to hold the preset data.
3887 ///
3888 /// @param[in] buffer_length
3889 /// Size of the buffer.
3890 ///
3891 HAPI_DECL HAPI_SetPreset( const HAPI_Session * session,
3892  HAPI_NodeId node_id,
3893  HAPI_PresetType preset_type,
3894  const char * preset_name,
3895  const char * buffer,
3896  int buffer_length );
3897 
3898 /// @defgroup Objects
3899 /// Functions for working with OBJ Nodes
3900 
3901 /// @brief Get the object info on an OBJ node.
3902 ///
3903 /// @ingroup Objects
3904 ///
3905 /// @param[in] session
3906 /// The session of Houdini you are interacting with.
3907 /// See @ref HAPI_Sessions for more on sessions.
3908 /// Pass NULL to just use the default in-process session.
3909 /// <!-- default NULL -->
3910 ///
3911 /// @param[in] node_id
3912 /// The node id.
3913 ///
3914 /// @param[out] object_info
3915 /// The output ::HAPI_ObjectInfo.
3916 ///
3917 HAPI_DECL HAPI_GetObjectInfo( const HAPI_Session * session,
3918  HAPI_NodeId node_id,
3919  HAPI_ObjectInfo * object_info );
3920 
3921 /// @brief Get the tranform of an OBJ node.
3922 ///
3923 /// @ingroup Objects
3924 ///
3925 /// @param[in] session
3926 /// The session of Houdini you are interacting with.
3927 /// See @ref HAPI_Sessions for more on sessions.
3928 /// Pass NULL to just use the default in-process session.
3929 /// <!-- default NULL -->
3930 ///
3931 /// @param[in] node_id
3932 /// The object node id.
3933 ///
3934 /// @param[in] relative_to_node_id
3935 /// The object node id for the object to which the returned
3936 /// transform will be relative to. Pass -1 or the node_id
3937 /// to just get the object's local transform.
3938 ///
3939 /// @param[in] rst_order
3940 /// The order of application of translation, rotation and
3941 /// scale.
3942 ///
3943 /// @param[out] transform
3944 /// The output ::HAPI_Transform transform.
3945 ///
3947  HAPI_NodeId node_id,
3948  HAPI_NodeId relative_to_node_id,
3949  HAPI_RSTOrder rst_order,
3950  HAPI_Transform * transform );
3951 
3952 /// @brief Compose a list of child object nodes given a parent node id.
3953 ///
3954 /// Use the @c object_count returned by this function to get the
3955 /// ::HAPI_ObjectInfo structs for each child object using
3956 /// ::HAPI_GetComposedObjectList().
3957 ///
3958 /// Note, if not using the @c categories arg, this is equivalent to:
3959 /// @code
3960 /// HAPI_ComposeChildNodeList(
3961 /// session, parent_node_id,
3962 /// HAPI_NODETYPE_OBJ,
3963 /// HAPI_NODEFLAGS_OBJ_GEOMETRY,
3964 /// true, &object_count );
3965 /// @endcode
3966 ///
3967 /// @ingroup Objects
3968 ///
3969 /// @param[in] session
3970 /// The session of Houdini you are interacting with.
3971 /// See @ref HAPI_Sessions for more on sessions.
3972 /// Pass NULL to just use the default in-process session.
3973 /// <!-- default NULL -->
3974 ///
3975 /// @param[in] parent_node_id
3976 /// The parent node id.
3977 ///
3978 /// @param[in] categories
3979 /// (Optional) Lets you filter object nodes by their render
3980 /// categories. This is a standard OBJ parameter, usually
3981 /// under the Render > Shading tab. If an OBJ node does not
3982 /// have this parameter, one can always add it as a spare.
3983 ///
3984 /// The value of this string argument should be NULL if not
3985 /// used or a space-separated list of category names.
3986 /// Multiple category names will be treated as an AND op.
3987 /// <!-- default NULL -->
3988 ///
3989 /// @param[out] object_count
3990 /// The number of object nodes currently under the parent.
3991 /// Use this count with a call to
3992 /// ::HAPI_GetComposedObjectList() to get the object infos.
3993 ///
3995  HAPI_NodeId parent_node_id,
3996  const char * categories,
3997  int * object_count );
3998 
3999 /// @brief Fill an array of ::HAPI_ObjectInfo structs.
4000 ///
4001 /// This is best used with ::HAPI_ComposeObjectList() with.
4002 ///
4003 /// @ingroup Objects
4004 ///
4005 /// @param[in] session
4006 /// The session of Houdini you are interacting with.
4007 /// See @ref HAPI_Sessions for more on sessions.
4008 /// Pass NULL to just use the default in-process session.
4009 /// <!-- default NULL -->
4010 ///
4011 /// @param[in] parent_node_id
4012 /// The parent node id.
4013 ///
4014 /// @param[out] object_infos_array
4015 /// Array of ::HAPI_ObjectInfo at least the size of
4016 /// @c length.
4017 ///
4018 /// @param[in] start
4019 /// At least @c 0 and at most @c object_count returned by
4020 /// ::HAPI_ComposeObjectList().
4021 /// <!-- default 0 -->
4022 ///
4023 /// @param[in] length
4024 /// Given @c object_count returned by
4025 /// ::HAPI_ComposeObjectList(), @c length should be at least
4026 /// @c 0 and at most <tt>object_count - start</tt>.
4027 /// <!-- source ::HAPI_ComposeObjectList - start -->
4028 ///
4030  HAPI_NodeId parent_node_id,
4031  HAPI_ObjectInfo * object_infos_array,
4032  int start, int length );
4033 
4034 /// @brief Fill an array of ::HAPI_Transform structs.
4035 ///
4036 /// This is best used with ::HAPI_ComposeObjectList() with.
4037 ///
4038 /// Note that these transforms will be relative to the
4039 /// @c parent_node_id originally given to ::HAPI_ComposeObjectList()
4040 /// and expected to be the same with this call. If @c parent_node_id
4041 /// is not an OBJ node, the transforms will be given as they are on
4042 /// the object node itself.
4043 ///
4044 /// @ingroup Objects
4045 ///
4046 /// @param[in] session
4047 /// The session of Houdini you are interacting with.
4048 /// See @ref HAPI_Sessions for more on sessions.
4049 /// Pass NULL to just use the default in-process session.
4050 /// <!-- default NULL -->
4051 ///
4052 /// @param[in] parent_node_id
4053 /// The parent node id. The object transforms will be
4054 /// relative to this node unless this node is not an OBJ.
4055 ///
4056 /// @param[in] rst_order
4057 /// The order of application of translation, rotation and
4058 /// scale.
4059 ///
4060 /// @param[out] transform_array
4061 /// Array of ::HAPI_Transform at least the size of
4062 /// length.
4063 ///
4064 /// @param[in] start
4065 /// At least @c 0 and at most @c object_count returned by
4066 /// ::HAPI_ComposeObjectList().
4067 /// <!-- default 0 -->
4068 ///
4069 /// @param[in] length
4070 /// Given @c object_count returned by
4071 /// ::HAPI_ComposeObjectList(), @c length should be at least
4072 /// @c 0 and at most <tt>object_count - start</tt>.
4073 /// <!-- source ::HAPI_ComposeObjectList - start -->
4074 ///
4076  HAPI_NodeId parent_node_id,
4077  HAPI_RSTOrder rst_order,
4078  HAPI_Transform * transform_array,
4079  int start, int length );
4080 
4081 /// @brief Get the node ids for the objects being instanced by an
4082 /// Instance OBJ node.
4083 ///
4084 /// @ingroup Objects
4085 ///
4086 /// @param[in] session
4087 /// The session of Houdini you are interacting with.
4088 /// See @ref HAPI_Sessions for more on sessions.
4089 /// Pass NULL to just use the default in-process session.
4090 /// <!-- default NULL -->
4091 ///
4092 /// @param[in] object_node_id
4093 /// The object node id.
4094 ///
4095 /// @param[out] instanced_node_id_array
4096 /// Array of ::HAPI_NodeId at least the size of length.
4097 ///
4098 /// @param[in] start
4099 /// At least @c 0 and at most @c object_count returned by
4100 /// ::HAPI_ComposeObjectList().
4101 /// <!-- default 0 -->
4102 ///
4103 /// @param[in] length
4104 /// Given @c object_count returned by
4105 /// ::HAPI_ComposeObjectList(), @c length should be at least
4106 /// @c 0 and at most <tt>object_count - start</tt>.
4107 /// <!-- source ::HAPI_ComposeObjectList - start -->
4108 ///
4110  HAPI_NodeId object_node_id,
4111  HAPI_NodeId * instanced_node_id_array,
4112  int start, int length );
4113 
4114 /// @deprecated Use HAPI_GetInstanceTransformsOnPart() instead (using Part 0 for
4115 /// previous behaviour).
4116 ///
4117 /// @brief Fill an array of ::HAPI_Transform structs with the transforms
4118 /// of each instance of this instancer object.
4119 ///
4120 /// @ingroup Objects
4121 ///
4122 /// @param[in] session
4123 /// The session of Houdini you are interacting with.
4124 /// See @ref HAPI_Sessions for more on sessions.
4125 /// Pass NULL to just use the default in-process session.
4126 /// <!-- default NULL -->
4127 ///
4128 /// @param[in] object_node_id
4129 /// The object node id.
4130 ///
4131 /// @param[in] rst_order
4132 /// The order of application of translation, rotation and
4133 /// scale.
4134 ///
4135 /// @param[out] transforms_array
4136 /// Array of ::HAPI_Transform at least the size of length.
4137 ///
4138 /// @param[in] start
4139 /// First index of range. Must be at least 0 and at
4140 /// most ::HAPI_PartInfo::pointCount - 1. This is the 0th
4141 /// part of the display geo of the instancer object node.
4142 /// <!-- default 0 -->
4143 ///
4144 /// @param[in] length
4145 /// Must be at least 0 and at most
4146 /// ::HAPI_PartInfo::pointCount - @p start. This is the 0th
4147 /// part of the display geo of the instancer object node.
4148 /// <!-- source ::HAPI_PartInfo::pointCount - start -->
4149 ///
4150 HAPI_DECL_DEPRECATED( 3.2.42, 18.0.150 )
4151 HAPI_GetInstanceTransforms( const HAPI_Session * session,
4152  HAPI_NodeId object_node_id,
4153  HAPI_RSTOrder rst_order,
4154  HAPI_Transform * transforms_array,
4155  int start, int length );
4156 
4157 /// @brief Fill an array of ::HAPI_Transform structs with the transforms
4158 /// of each instance of this instancer object for a given part.
4159 ///
4160 /// @ingroup Objects
4161 ///
4162 /// @param[in] session
4163 /// The session of Houdini you are interacting with.
4164 /// See @ref HAPI_Sessions for more on sessions.
4165 /// Pass NULL to just use the default in-process session.
4166 /// <!-- default NULL -->
4167 ///
4168 /// @param[in] node_id
4169 /// The object node id.
4170 ///
4171 /// @param[in] part_id
4172 /// The part id.
4173 ///
4174 /// @param[in] rst_order
4175 /// The order of application of translation, rotation and
4176 /// scale.
4177 ///
4178 /// @param[out] transforms_array
4179 /// Array of ::HAPI_Transform at least the size of length.
4180 ///
4181 /// @param[in] start
4182 /// First index of range. Must be at least 0 and at
4183 /// most ::HAPI_PartInfo::pointCount - 1. This is the 0th
4184 /// part of the display geo of the instancer object node.
4185 /// <!-- default 0 -->
4186 ///
4187 /// @param[in] length
4188 /// Must be at least 0 and at most
4189 /// ::HAPI_PartInfo::pointCount - @p start. This is the 0th
4190 /// part of the display geo of the instancer object node.
4191 /// <!-- source ::HAPI_PartInfo::pointCount - start -->
4192 ///
4194  HAPI_NodeId node_id,
4195  HAPI_PartId part_id,
4196  HAPI_RSTOrder rst_order,
4197  HAPI_Transform * transforms_array,
4198  int start, int length );
4199 
4200 /// @brief Set the transform of an individual object. Note that the object
4201 /// nodes have to either be editable or have their transform
4202 /// parameters exposed at the asset level. This won't work otherwise.
4203 ///
4204 /// @ingroup Objects
4205 ///
4206 /// @param[in] session
4207 /// The session of Houdini you are interacting with.
4208 /// See @ref HAPI_Sessions for more on sessions.
4209 /// Pass NULL to just use the default in-process session.
4210 /// <!-- default NULL -->
4211 ///
4212 /// @param[in] node_id
4213 /// The object node id.
4214 ///
4215 /// @param[in] trans
4216 /// A ::HAPI_TransformEuler that stores the transform.
4217 ///
4219  HAPI_NodeId node_id,
4220  const HAPI_TransformEuler * trans );
4221 
4222 /// @defgroup GeometryGetters Geometry Getters
4223 /// Functions for reading Geometry (SOP) data
4224 
4225 /// @brief Get the display geo (SOP) node inside an Object node. If there
4226 /// there are multiple display SOP nodes, only the first one is
4227 /// returned. If the node is a display SOP itself, even if a network,
4228 /// it will return its own geo info. If the node is a SOP but not
4229 /// a network and not the display SOP, this function will fail.
4230 ///
4231 /// The above implies that you can safely call this function on both
4232 /// OBJ and SOP asset nodes and get the same (equivalent) geometry
4233 /// display node back. SOP asset nodes will simply return themselves.
4234 ///
4235 /// @ingroup GeometryGetters
4236 ///
4237 /// @param[in] session
4238 /// The session of Houdini you are interacting with.
4239 /// See @ref HAPI_Sessions for more on sessions.
4240 /// Pass NULL to just use the default in-process session.
4241 /// <!-- default NULL -->
4242 ///
4243 /// @param[in] object_node_id
4244 /// The object node id.
4245 ///
4246 /// @param[out] geo_info
4247 /// ::HAPI_GeoInfo return value.
4248 ///
4250  HAPI_NodeId object_node_id,
4251  HAPI_GeoInfo * geo_info );
4252 
4253 /// @brief Get the geometry info struct (::HAPI_GeoInfo) on a SOP node.
4254 ///
4255 /// @ingroup GeometryGetters
4256 ///
4257 /// @param[in] session
4258 /// The session of Houdini you are interacting with.
4259 /// See @ref HAPI_Sessions for more on sessions.
4260 /// Pass NULL to just use the default in-process session.
4261 /// <!-- default NULL -->
4262 ///
4263 /// @param[in] node_id
4264 /// The node id.
4265 ///
4266 /// @param[out] geo_info
4267 /// ::HAPI_GeoInfo return value.
4268 ///
4269 HAPI_DECL HAPI_GetGeoInfo( const HAPI_Session * session,
4270  HAPI_NodeId node_id,
4271  HAPI_GeoInfo * geo_info );
4272 
4273 /// @brief Get a particular part info struct.
4274 ///
4275 /// @ingroup GeometryGetters
4276 ///
4277 /// @param[in] session
4278 /// The session of Houdini you are interacting with.
4279 /// See @ref HAPI_Sessions for more on sessions.
4280 /// Pass NULL to just use the default in-process session.
4281 /// <!-- default NULL -->
4282 ///
4283 /// @param[in] node_id
4284 /// The SOP node id.
4285 ///
4286 /// @param[in] part_id
4287 /// The part id.
4288 ///
4289 /// @param[out] part_info
4290 /// ::HAPI_PartInfo return value.
4291 ///
4292 HAPI_DECL HAPI_GetPartInfo( const HAPI_Session * session,
4293  HAPI_NodeId node_id,
4294  HAPI_PartId part_id,
4295  HAPI_PartInfo * part_info );
4296 
4297 /// @brief Get the array of faces where the nth integer in the array is
4298 /// the number of vertices the nth face has.
4299 ///
4300 /// @ingroup GeometryGetters
4301 ///
4302 /// @param[in] session
4303 /// The session of Houdini you are interacting with.
4304 /// See @ref HAPI_Sessions for more on sessions.
4305 /// Pass NULL to just use the default in-process session.
4306 /// <!-- default NULL -->
4307 ///
4308 /// @param[in] node_id
4309 /// The node id.
4310 ///
4311 /// @param[in] part_id
4312 /// The part id.
4313 ///
4314 /// @param[out] face_counts_array
4315 /// An integer array at least the size of length.
4316 ///
4317 /// @param[in] start
4318 /// First index of range. Must be at least 0 and at
4319 /// most ::HAPI_PartInfo::faceCount - 1.
4320 /// <!-- default 0 -->
4321 ///
4322 /// @param[in] length
4323 /// Must be at least 0 and at most
4324 /// ::HAPI_PartInfo::faceCount - @p start.
4325 /// <!-- source ::HAPI_PartInfo::faceCount - start -->
4326 ///
4327 HAPI_DECL HAPI_GetFaceCounts( const HAPI_Session * session,
4328  HAPI_NodeId node_id,
4329  HAPI_PartId part_id,
4330  int * face_counts_array,
4331  int start, int length );
4332 
4333 /// @brief Get array containing the vertex-point associations where the
4334 /// ith element in the array is the point index the ith vertex
4335 /// associates with.
4336 ///
4337 /// @ingroup GeometryGetters
4338 ///
4339 /// @param[in] session
4340 /// The session of Houdini you are interacting with.
4341 /// See @ref HAPI_Sessions for more on sessions.
4342 /// Pass NULL to just use the default in-process session.
4343 /// <!-- default NULL -->
4344 ///
4345 /// @param[in] node_id
4346 /// The node id.
4347 ///
4348 /// @param[in] part_id
4349 /// The part id.
4350 ///
4351 /// @param[out] vertex_list_array
4352 /// An integer array at least the size of length.
4353 ///
4354 /// @param[in] start
4355 /// First index of range. Must be at least 0 and at
4356 /// most ::HAPI_PartInfo::vertexCount - 1.
4357 /// <!-- default 0 -->
4358 ///
4359 /// @param[in] length
4360 /// Must be at least 0 and at most
4361 /// ::HAPI_PartInfo::vertexCount - @p start.
4362 /// <!-- source ::HAPI_PartInfo::vertexCount - start -->
4363 ///
4364 HAPI_DECL HAPI_GetVertexList( const HAPI_Session * session,
4365  HAPI_NodeId node_id,
4366  HAPI_PartId part_id,
4367  int * vertex_list_array,
4368  int start, int length );
4369 
4370 /// @defgroup Attributes
4371 /// Functions for working with attributes.
4372 
4373 /// @brief Get the attribute info struct for the attribute specified by name.
4374 ///
4375 /// @ingroup GeometryGetters
4376 ///
4377 /// @param[in] session
4378 /// The session of Houdini you are interacting with.
4379 /// See @ref HAPI_Sessions for more on sessions.
4380 /// Pass NULL to just use the default in-process session.
4381 /// <!-- default NULL -->
4382 ///
4383 /// @param[in] node_id
4384 /// The node id.
4385 ///
4386 /// @param[in] part_id
4387 /// The part id.
4388 ///
4389 /// @param[in] name
4390 /// Attribute name.
4391 ///
4392 /// @param[in] owner
4393 /// Attribute owner.
4394 ///
4395 /// @param[out] attr_info
4396 /// ::HAPI_AttributeInfo to be filled. Check
4397 /// ::HAPI_AttributeInfo::exists to see if this attribute
4398 /// exists.
4399 ///
4401  HAPI_NodeId node_id,
4402  HAPI_PartId part_id,
4403  const char * name,
4404  HAPI_AttributeOwner owner,
4405  HAPI_AttributeInfo * attr_info );
4406 
4407 /// @brief Get list of attribute names by attribute owner. Note that the
4408 /// name string handles are only valid until the next time this
4409 /// function is called.
4410 ///
4411 /// @ingroup GeometryGetters
4412 ///
4413 /// @param[in] session
4414 /// The session of Houdini you are interacting with.
4415 /// See @ref HAPI_Sessions for more on sessions.
4416 /// Pass NULL to just use the default in-process session.
4417 /// <!-- default NULL -->
4418 ///
4419 /// @param[in] node_id
4420 /// The node id.
4421 ///
4422 /// @param[in] part_id
4423 /// The part id.
4424 ///
4425 /// @param[in] owner
4426 /// The ::HAPI_AttributeOwner enum value specifying the
4427 /// owner of the attribute.
4428 ///
4429 /// @param[out] attribute_names_array
4430 /// Array of ints (string handles) to house the
4431 /// attribute names. Should be exactly the size of the
4432 /// appropriate attribute owner type count
4433 /// in ::HAPI_PartInfo.
4434 ///
4435 /// @param[in] count
4436 /// Sanity check count. Must be equal to the appropriate
4437 /// attribute owner type count in ::HAPI_PartInfo.
4438 ///
4440  HAPI_NodeId node_id,
4441  HAPI_PartId part_id,
4442  HAPI_AttributeOwner owner,
4443  HAPI_StringHandle * attribute_names_array,
4444  int count );
4445 
4446 /// @brief Get attribute integer data.
4447 ///
4448 /// @ingroup GeometryGetters
4449 ///
4450 /// @param[in] session
4451 /// The session of Houdini you are interacting with.
4452 /// See @ref HAPI_Sessions for more on sessions.
4453 /// Pass NULL to just use the default in-process session.
4454 /// <!-- default NULL -->
4455 ///
4456 /// @param[in] node_id
4457 /// The node id.
4458 ///
4459 /// @param[in] part_id
4460 /// The part id.
4461 ///
4462 /// @param[in] name
4463 /// Attribute name.
4464 ///
4465 /// @param[in] attr_info
4466 /// ::HAPI_AttributeInfo used as input for what tuple size.
4467 /// you want. Also contains some sanity checks like
4468 /// data type. Generally should be the same struct
4469 /// returned by ::HAPI_GetAttributeInfo().
4470 ///
4471 /// @param[in] stride
4472 /// Specifies how many items to skip over for each element.
4473 /// With a stride of -1, the stride will be set to
4474 /// @c attr_info->tuple_size. Otherwise, the stride will be
4475 /// set to the maximum of @c attr_info->tuple_size and
4476 /// @c stride.
4477 ///
4478 /// @param[out] data_array
4479 /// An integer array at least the size of
4480 /// <tt>length * ::HAPI_AttributeInfo::tupleSize</tt>.
4481 ///
4482 /// @param[in] start
4483 /// First index of range. Must be at least 0 and at
4484 /// most ::HAPI_AttributeInfo::count - 1.
4485 /// <!-- default 0 -->
4486 ///
4487 /// @param[in] length
4488 /// Must be at least 0 and at most
4489 /// ::HAPI_AttributeInfo::count - @p start.
4490 /// Note, if 0 is passed for length, the function will just
4491 /// do nothing and return ::HAPI_RESULT_SUCCESS.
4492 /// <!-- source ::HAPI_AttributeInfo::count - start -->
4493 ///
4495  HAPI_NodeId node_id,
4496  HAPI_PartId part_id,
4497  const char * name,
4498  HAPI_AttributeInfo * attr_info,
4499  int stride,
4500  int * data_array,
4501  int start, int length );
4502 
4503 /// @brief Get array attribute integer data.
4504 /// Each entry in an array attribute can have varying array lengths.
4505 /// Therefore the array values are returned as a flat array, with
4506 /// another sizes array containing the lengths of each array entry.
4507 ///
4508 /// @ingroup GeometryGetters
4509 ///
4510 /// @param[in] session
4511 /// The session of Houdini you are interacting with.
4512 /// See @ref HAPI_Sessions for more on sessions.
4513 /// Pass NULL to just use the default in-process session.
4514 /// <!-- default NULL -->
4515 ///
4516 /// @param[in] node_id
4517 /// The node id.
4518 ///
4519 /// @param[in] part_id
4520 /// The part id.
4521 ///
4522 /// @param[in] name
4523 /// Attribute name.
4524 ///
4525 /// @param[in] attr_info
4526 /// ::HAPI_AttributeInfo used as input for what tuple size.
4527 /// you want. Also contains some sanity checks like
4528 /// data type. Generally should be the same struct
4529 /// returned by ::HAPI_GetAttributeInfo().
4530 ///
4531 /// @param[out] data_fixed_array
4532 /// An integer array at least the size of
4533 /// <tt>::HAPI_AttributeInfo::totalArrayElements</tt>.
4534 ///
4535 /// @param[in] data_fixed_length
4536 /// Must be <tt>::HAPI_AttributeInfo::totalArrayElements</tt>.
4537 /// <!-- source ::HAPI_AttributeInfo::totalArrayElements -->
4538 ///
4539 /// @param[out] sizes_fixed_array
4540 /// An integer array at least the size of
4541 /// <tt>sizes_fixed_length</tt> to hold the size of each entry.
4542 /// <!-- source ::HAPI_AttributeInfo::count -->
4543 ///
4544 /// @param[in] start
4545 /// First index of range. Must be at least 0 and at
4546 /// most ::HAPI_AttributeInfo::count - 1.
4547 /// <!-- default 0 -->
4548 ///
4549 /// @param[in] sizes_fixed_length
4550 /// Must be at least 0 and at most
4551 /// ::HAPI_AttributeInfo::count - @p start.
4552 /// Note, if 0 is passed for length, the function will just
4553 /// do nothing and return ::HAPI_RESULT_SUCCESS.
4554 /// <!-- source ::HAPI_AttributeInfo::count - start -->
4555 ///
4557  HAPI_NodeId node_id,
4558  HAPI_PartId part_id,
4559  const char * name,
4560  HAPI_AttributeInfo * attr_info,
4561  int * data_fixed_array,
4562  int data_fixed_length,
4563  int * sizes_fixed_array,
4564  int start, int sizes_fixed_length );
4565 
4566 /// @brief Get attribute 64-bit integer data.
4567 ///
4568 /// @ingroup GeometryGetters
4569 ///
4570 /// @param[in] session
4571 /// The session of Houdini you are interacting with.
4572 /// See @ref HAPI_Sessions for more on sessions.
4573 /// Pass NULL to just use the default in-process session.
4574 /// <!-- default NULL -->
4575 ///
4576 /// @param[in] node_id
4577 /// The node id.
4578 ///
4579 /// @param[in] part_id
4580 /// The part id.
4581 ///
4582 /// @param[in] name
4583 /// Attribute name.
4584 ///
4585 /// @param[in] attr_info
4586 /// ::HAPI_AttributeInfo used as input for what tuple size.
4587 /// you want. Also contains some sanity checks like
4588 /// data type. Generally should be the same struct
4589 /// returned by ::HAPI_GetAttributeInfo().
4590 ///
4591 /// @param[in] stride
4592 /// Specifies how many items to skip over for each element.
4593 /// With a stride of -1, the stride will be set to
4594 /// @c attr_info->tuple_size. Otherwise, the stride will be
4595 /// set to the maximum of @c attr_info->tuple_size and
4596 /// @c stride.
4597 ///
4598 /// @param[out] data_array
4599 /// An 64-bit integer array at least the size of
4600 /// <tt>length * ::HAPI_AttributeInfo::tupleSize</tt>.
4601 ///
4602 /// @param[in] start
4603 /// First index of range. Must be at least 0 and at
4604 /// most ::HAPI_AttributeInfo::count - 1.
4605 /// <!-- default 0 -->
4606 ///
4607 /// @param[in] length
4608 /// Must be at least 0 and at most
4609 /// ::HAPI_AttributeInfo::count - @p start.
4610 /// Note, if 0 is passed for length, the function will just
4611 /// do nothing and return ::HAPI_RESULT_SUCCESS.
4612 /// <!-- source ::HAPI_AttributeInfo::count - start -->
4613 ///
4615  HAPI_NodeId node_id,
4616  HAPI_PartId part_id,
4617  const char * name,
4618  HAPI_AttributeInfo * attr_info,
4619  int stride,
4620  HAPI_Int64 * data_array,
4621  int start, int length );
4622 
4623 /// @brief Get array attribute 64-bit integer data.
4624 /// Each entry in an array attribute can have varying array lengths.
4625 /// Therefore the array values are returned as a flat array, with
4626 /// another sizes array containing the lengths of each array entry.
4627 ///
4628 /// @ingroup GeometryGetters
4629 ///
4630 /// @param[in] session
4631 /// The session of Houdini you are interacting with.
4632 /// See @ref HAPI_Sessions for more on sessions.
4633 /// Pass NULL to just use the default in-process session.
4634 /// <!-- default NULL -->
4635 ///
4636 /// @param[in] node_id
4637 /// The node id.
4638 ///
4639 /// @param[in] part_id
4640 /// The part id.
4641 ///
4642 /// @param[in] name
4643 /// Attribute name.
4644 ///
4645 /// @param[in] attr_info
4646 /// ::HAPI_AttributeInfo used as input for what tuple size.
4647 /// you want. Also contains some sanity checks like
4648 /// data type. Generally should be the same struct
4649 /// returned by ::HAPI_GetAttributeInfo().
4650 ///
4651 /// @param[out] data_fixed_array
4652 /// An 64-bit integer array at least the size of
4653 /// <tt>::HAPI_AttributeInfo::totalArrayElements</tt>.
4654 ///
4655 /// @param[in] data_fixed_length
4656 /// Must be <tt>::HAPI_AttributeInfo::totalArrayElements</tt>.
4657 /// <!-- source ::HAPI_AttributeInfo::totalArrayElements -->
4658 ///
4659 /// @param[out] sizes_fixed_array
4660 /// An integer array at least the size of
4661 /// <tt>sizes_fixed_length</tt> to hold the size of each entry.
4662 ///
4663 /// @param[in] start
4664 /// First index of range. Must be at least 0 and at
4665 /// most ::HAPI_AttributeInfo::count - 1.
4666 /// <!-- default 0 -->
4667 ///
4668 /// @param[in] sizes_fixed_length
4669 /// Must be at least 0 and at most
4670 /// ::HAPI_AttributeInfo::count - @p start.
4671 /// Note, if 0 is passed for length, the function will just
4672 /// do nothing and return ::HAPI_RESULT_SUCCESS.
4673 /// <!-- source ::HAPI_AttributeInfo::count - start -->
4674 ///
4676  HAPI_NodeId node_id,
4677  HAPI_PartId part_id,
4678  const char * name,
4679  HAPI_AttributeInfo * attr_info,
4680  HAPI_Int64 * data_fixed_array,
4681  int data_fixed_length,
4682  int * sizes_fixed_array,
4683  int start, int sizes_fixed_length );
4684 
4685 /// @brief Get attribute float data.
4686 ///
4687 /// @ingroup GeometryGetters
4688 ///
4689 /// @param[in] session
4690 /// The session of Houdini you are interacting with.
4691 /// See @ref HAPI_Sessions for more on sessions.
4692 /// Pass NULL to just use the default in-process session.
4693 /// <!-- default NULL -->
4694 ///
4695 /// @param[in] node_id
4696 /// The node id.
4697 ///
4698 /// @param[in] part_id
4699 /// The part id.
4700 ///
4701 /// @param[in] name
4702 /// Attribute name.
4703 ///
4704 /// @param[in] attr_info
4705 /// ::HAPI_AttributeInfo used as input for what tuple size.
4706 /// you want. Also contains some sanity checks like
4707 /// data type. Generally should be the same struct
4708 /// returned by ::HAPI_GetAttributeInfo().
4709 ///
4710 /// @param[in] stride
4711 /// Specifies how many items to skip over for each element.
4712 /// With a stride of -1, the stride will be set to
4713 /// @c attr_info->tuple_size. Otherwise, the stride will be
4714 /// set to the maximum of @c attr_info->tuple_size and
4715 /// @c stride.
4716 ///
4717 /// @param[out] data_array
4718 /// An float array at least the size of
4719 /// <tt>length * ::HAPI_AttributeInfo::tupleSize</tt>.
4720 ///
4721 /// @param[in] start
4722 /// First index of range. Must be at least 0 and at
4723 /// most ::HAPI_AttributeInfo::count - 1.
4724 /// <!-- default 0 -->
4725 ///
4726 /// @param[in] length
4727 /// Must be at least 0 and at most
4728 /// ::HAPI_AttributeInfo::count - @p start.
4729 /// Note, if 0 is passed for length, the function will just
4730 /// do nothing and return ::HAPI_RESULT_SUCCESS.
4731 /// <!-- source ::HAPI_AttributeInfo::count - start -->
4732 ///
4734  HAPI_NodeId node_id,
4735  HAPI_PartId part_id,
4736  const char * name,
4737  HAPI_AttributeInfo * attr_info,
4738  int stride,
4739  float * data_array,
4740  int start, int length );
4741 
4742 /// @brief Get array attribute float data.
4743 /// Each entry in an array attribute can have varying array lengths.
4744 /// Therefore the array values are returned as a flat array, with
4745 /// another sizes array containing the lengths of each array entry.
4746 ///
4747 /// @ingroup GeometryGetters
4748 ///
4749 /// @param[in] session
4750 /// The session of Houdini you are interacting with.
4751 /// See @ref HAPI_Sessions for more on sessions.
4752 /// Pass NULL to just use the default in-process session.
4753 /// <!-- default NULL -->
4754 ///
4755 /// @param[in] node_id
4756 /// The node id.
4757 ///
4758 /// @param[in] part_id
4759 /// The part id.
4760 ///
4761 /// @param[in] name
4762 /// Attribute name.
4763 ///
4764 /// @param[in] attr_info
4765 /// ::HAPI_AttributeInfo used as input for what tuple size.
4766 /// you want. Also contains some sanity checks like
4767 /// data type. Generally should be the same struct
4768 /// returned by ::HAPI_GetAttributeInfo().
4769 ///
4770 /// @param[out] data_fixed_array
4771 /// An float array at least the size of
4772 /// <tt>::HAPI_AttributeInfo::totalArrayElements</tt>.
4773 ///
4774 /// @param[in] data_fixed_length
4775 /// Must be <tt>::HAPI_AttributeInfo::totalArrayElements</tt>.
4776 /// <!-- source ::HAPI_AttributeInfo::totalArrayElements -->
4777 ///
4778 /// @param[out] sizes_fixed_array
4779 /// An integer array at least the size of
4780 /// <tt>sizes_fixed_length</tt> to hold the size of each entry.
4781 ///
4782 /// @param[in] start
4783 /// First index of range. Must be at least 0 and at
4784 /// most ::HAPI_AttributeInfo::count - 1.
4785 /// <!-- default 0 -->
4786 ///
4787 /// @param[in] sizes_fixed_length
4788 /// Must be at least 0 and at most
4789 /// ::HAPI_AttributeInfo::count - @p start.
4790 /// Note, if 0 is passed for length, the function will just
4791 /// do nothing and return ::HAPI_RESULT_SUCCESS.
4792 /// <!-- source ::HAPI_AttributeInfo::count - start -->
4793 ///
4795  HAPI_NodeId node_id,
4796  HAPI_PartId part_id,
4797  const char * name,
4798  HAPI_AttributeInfo * attr_info,
4799  float * data_fixed_array,
4800  int data_fixed_length,
4801  int * sizes_fixed_array,
4802  int start, int sizes_fixed_length );
4803 
4804 /// @brief Get 64-bit attribute float data.
4805 ///
4806 /// @ingroup GeometryGetters
4807 ///
4808 /// @param[in] session
4809 /// The session of Houdini you are interacting with.
4810 /// See @ref HAPI_Sessions for more on sessions.
4811 /// Pass NULL to just use the default in-process session.
4812 /// <!-- default NULL -->
4813 ///
4814 /// @param[in] node_id
4815 /// The node id.
4816 ///
4817 /// @param[in] part_id
4818 /// The part id.
4819 ///
4820 /// @param[in] name
4821 /// Attribute name.
4822 ///
4823 /// @param[in] attr_info
4824 /// ::HAPI_AttributeInfo used as input for what tuple size.
4825 /// you want. Also contains some sanity checks like
4826 /// data type. Generally should be the same struct
4827 /// returned by ::HAPI_GetAttributeInfo().
4828 ///
4829 /// @param[in] stride
4830 /// Specifies how many items to skip over for each element.
4831 /// With a stride of -1, the stride will be set to
4832 /// @c attr_info->tuple_size. Otherwise, the stride will be
4833 /// set to the maximum of @c attr_info->tuple_size and
4834 /// @c stride.
4835 ///
4836 /// @param[out] data_array
4837 /// An 64-bit float array at least the size of
4838 /// <tt>length * ::HAPI_AttributeInfo::tupleSize</tt>.
4839 ///
4840 /// @param[in] start
4841 /// First index of range. Must be at least 0 and at
4842 /// most ::HAPI_AttributeInfo::count - 1.
4843 /// <!-- default 0 -->
4844 ///
4845 /// @param[in] length
4846 /// Must be at least 0 and at most
4847 /// ::HAPI_AttributeInfo::count - @p start.
4848 /// Note, if 0 is passed for length, the function will just
4849 /// do nothing and return ::HAPI_RESULT_SUCCESS.
4850 /// <!-- source ::HAPI_AttributeInfo::count - start -->
4851 ///
4853  HAPI_NodeId node_id,
4854  HAPI_PartId part_id,
4855  const char * name,
4856  HAPI_AttributeInfo * attr_info,
4857  int stride,
4858  double * data_array,
4859  int start, int length );
4860 
4861 /// @brief Get array attribute 64-bit float data.
4862 /// Each entry in an array attribute can have varying array lengths.
4863 /// Therefore the array values are returned as a flat array, with
4864 /// another sizes array containing the lengths of each array entry.
4865 ///
4866 /// @ingroup GeometryGetters
4867 ///
4868 /// @param[in] session
4869 /// The session of Houdini you are interacting with.
4870 /// See @ref HAPI_Sessions for more on sessions.
4871 /// Pass NULL to just use the default in-process session.
4872 /// <!-- default NULL -->
4873 ///
4874 /// @param[in] node_id
4875 /// The node id.
4876 ///
4877 /// @param[in] part_id
4878 /// The part id.
4879 ///
4880 /// @param[in] name
4881 /// Attribute name.
4882 ///
4883 /// @param[in] attr_info
4884 /// ::HAPI_AttributeInfo used as input for the.
4885 /// totalArrayElements. Also contains some sanity checks like
4886 /// data type. Generally should be the same struct
4887 /// returned by ::HAPI_GetAttributeInfo().
4888 ///
4889 /// @param[out] data_fixed_array
4890 /// An 64-bit float array at least the size of
4891 /// <tt>::HAPI_AttributeInfo::totalArrayElements</tt>.
4892 ///
4893 /// @param[in] data_fixed_length
4894 /// Must be <tt>::HAPI_AttributeInfo::totalArrayElements</tt>.
4895 /// <!-- source ::HAPI_AttributeInfo::totalArrayElements -->
4896 ///
4897 /// @param[out] sizes_fixed_array
4898 /// An integer array at least the size of
4899 /// <tt>sizes_fixed_length</tt> to hold the size of each entry.
4900 ///
4901 /// @param[in] start
4902 /// First index of range. Must be at least 0 and at
4903 /// most ::HAPI_AttributeInfo::count - 1.
4904 /// <!-- default 0 -->
4905 ///
4906 /// @param[in] sizes_fixed_length
4907 /// Must be at least 0 and at most
4908 /// ::HAPI_AttributeInfo::count - @p start.
4909 /// Note, if 0 is passed for length, the function will just
4910 /// do nothing and return ::HAPI_RESULT_SUCCESS.
4911 /// <!-- source ::HAPI_AttributeInfo::count - start -->
4912 ///
4914  HAPI_NodeId node_id,
4915  HAPI_PartId part_id,
4916  const char * name,
4917  HAPI_AttributeInfo * attr_info,
4918  double * data_fixed_array,
4919  int data_fixed_length,
4920  int * sizes_fixed_array,
4921  int start, int sizes_fixed_length );
4922 
4923 /// @brief Get attribute string data. Note that the string handles
4924 /// returned are only valid until the next time this function
4925 /// is called.
4926 ///
4927 /// @ingroup GeometryGetters
4928 ///
4929 /// @param[in] session
4930 /// The session of Houdini you are interacting with.
4931 /// See @ref HAPI_Sessions for more on sessions.
4932 /// Pass NULL to just use the default in-process session.
4933 /// <!-- default NULL -->
4934 ///
4935 /// @param[in] node_id
4936 /// The node id.
4937 ///
4938 /// @param[in] part_id
4939 /// The part id.
4940 ///
4941 /// @param[in] name
4942 /// Attribute name.
4943 ///
4944 /// @param[in] attr_info
4945 /// ::HAPI_AttributeInfo used as input for what tuple size.
4946 /// you want. Also contains some sanity checks like
4947 /// data type. Generally should be the same struct
4948 /// returned by ::HAPI_GetAttributeInfo().
4949 ///
4950 /// @param[out] data_array
4951 /// An ::HAPI_StringHandle array at least the size of
4952 /// <tt>length * ::HAPI_AttributeInfo::tupleSize</tt>.
4953 ///
4954 /// @param[in] start
4955 /// First index of range. Must be at least 0 and at
4956 /// most ::HAPI_AttributeInfo::count - 1.
4957 /// <!-- default 0 -->
4958 ///
4959 /// @param[in] length
4960 /// Must be at least 0 and at most
4961 /// ::HAPI_AttributeInfo::count - @p start.
4962 /// Note, if 0 is passed for length, the function will just
4963 /// do nothing and return ::HAPI_RESULT_SUCCESS.
4964 /// <!-- source ::HAPI_AttributeInfo::count - start -->
4965 ///
4967  HAPI_NodeId node_id,
4968  HAPI_PartId part_id,
4969  const char * name,
4970  HAPI_AttributeInfo * attr_info,
4971  HAPI_StringHandle * data_array,
4972  int start, int length );
4973 
4974 /// @brief Get array attribute string data.
4975 /// Each entry in an array attribute can have varying array lengths.
4976 /// Therefore the array values are returned as a flat array, with
4977 /// another sizes array containing the lengths of each array entry.
4978 /// Note that the string handles returned are only valid until
4979 /// the next time this function is called.
4980 ///
4981 /// @ingroup GeometryGetters
4982 ///
4983 /// @param[in] session
4984 /// The session of Houdini you are interacting with.
4985 /// See @ref HAPI_Sessions for more on sessions.
4986 /// Pass NULL to just use the default in-process session.
4987 /// <!-- default NULL -->
4988 ///
4989 /// @param[in] node_id
4990 /// The node id.
4991 ///
4992 /// @param[in] part_id
4993 /// The part id.
4994 ///
4995 /// @param[in] name
4996 /// Attribute name.
4997 ///
4998 /// @param[in] attr_info
4999 /// ::HAPI_AttributeInfo used as input for the.
5000 /// totalArrayElements. Also contains some sanity checks like
5001 /// data type. Generally should be the same struct
5002 /// returned by ::HAPI_GetAttributeInfo().
5003 ///
5004 /// @param[out] data_fixed_array
5005 /// An ::HAPI_StringHandle array at least the size of
5006 /// <tt>::HAPI_AttributeInfo::totalArrayElements</tt>.
5007 ///
5008 /// @param[in] data_fixed_length
5009 /// Must be <tt>::HAPI_AttributeInfo::totalArrayElements</tt>.
5010 /// <!-- source ::HAPI_AttributeInfo::totalArrayElements -->
5011 ///
5012 /// @param[out] sizes_fixed_array
5013 /// An integer array at least the size of
5014 /// <tt>sizes_fixed_length</tt> to hold the size of each entry.
5015 ///
5016 /// @param[in] start
5017 /// First index of range. Must be at least 0 and at
5018 /// most ::HAPI_AttributeInfo::count - 1.
5019 /// <!-- default 0 -->
5020 ///
5021 /// @param[in] sizes_fixed_length
5022 /// Must be at least 0 and at most
5023 /// ::HAPI_AttributeInfo::count - @p start.
5024 /// Note, if 0 is passed for length, the function will just
5025 /// do nothing and return ::HAPI_RESULT_SUCCESS.
5026 /// <!-- source ::HAPI_AttributeInfo::count - start -->
5027 ///
5029  HAPI_NodeId node_id,
5030  HAPI_PartId part_id,
5031  const char * name,
5032  HAPI_AttributeInfo * attr_info,
5033  HAPI_StringHandle * data_fixed_array,
5034  int data_fixed_length,
5035  int * sizes_fixed_array,
5036  int start, int sizes_fixed_length );
5037 
5038 /// @brief Get group names for an entire geo. Please note that this
5039 /// function is NOT per-part, but it is per-geo. The companion
5040 /// function ::HAPI_GetGroupMembership() IS per-part. Also keep
5041 /// in mind that the name string handles are only
5042 /// valid until the next time this function is called.
5043 ///
5044 /// @ingroup GeometryGetters
5045 ///
5046 /// @param[in] session
5047 /// The session of Houdini you are interacting with.
5048 /// See @ref HAPI_Sessions for more on sessions.
5049 /// Pass NULL to just use the default in-process session.
5050 /// <!-- default NULL -->
5051 ///
5052 /// @param[in] node_id
5053 /// The node id.
5054 ///
5055 /// @param[in] group_type
5056 /// The group type.
5057 ///
5058 /// @param[out] group_names_array
5059 /// The array of names to be filled. Should be the size
5060 /// given by ::HAPI_GeoInfo_GetGroupCountByType() with
5061 /// @p group_type and the ::HAPI_GeoInfo of @p geo_id.
5062 /// @note These string handles are only valid until the
5063 /// next call to ::HAPI_GetGroupNames().
5064 ///
5065 /// @param[in] group_count
5066 /// Sanity check. Should be less than or equal to the size
5067 /// of @p group_names.
5068 ///
5069 HAPI_DECL HAPI_GetGroupNames( const HAPI_Session * session,
5070  HAPI_NodeId node_id,
5071  HAPI_GroupType group_type,
5072  HAPI_StringHandle * group_names_array,
5073  int group_count );
5074 
5075 /// @brief Get group membership.
5076 ///
5077 /// @ingroup GeometryGetters
5078 ///
5079 /// @param[in] session
5080 /// The session of Houdini you are interacting with.
5081 /// See @ref HAPI_Sessions for more on sessions.
5082 /// Pass NULL to just use the default in-process session.
5083 /// <!-- default NULL -->
5084 ///
5085 /// @param[in] node_id
5086 /// The node id.
5087 ///
5088 /// @param[in] part_id
5089 /// The part id.
5090 ///
5091 /// @param[in] group_type
5092 /// The group type.
5093 ///
5094 /// @param[in] group_name
5095 /// The group name.
5096 ///
5097 /// @param[out] membership_array_all_equal
5098 /// (optional) Quick way to determine if all items are in
5099 /// the given group or all items our not in the group.
5100 /// You can just pass NULL here if not interested.
5101 ///
5102 /// @param[out] membership_array
5103 /// Array of ints that represent the membership of this
5104 /// group. Should be the size given by
5105 /// ::HAPI_PartInfo_GetElementCountByGroupType() with
5106 /// @p group_type and the ::HAPI_PartInfo of @p part_id.
5107 ///
5108 /// @param[in] start
5109 /// Start offset into the membership array. Must be
5110 /// less than ::HAPI_PartInfo_GetElementCountByGroupType().
5111 /// <!-- default 0 -->
5112 ///
5113 /// @param[in] length
5114 /// Should be less than or equal to the size
5115 /// of @p membership_array.
5116 /// <!-- source ::HAPI_PartInfo_GetElementCountByGroupType -->
5117 ///
5119  HAPI_NodeId node_id,
5120  HAPI_PartId part_id,
5121  HAPI_GroupType group_type,
5122  const char * group_name,
5123  HAPI_Bool * membership_array_all_equal,
5124  int * membership_array,
5125  int start, int length );
5126 
5127 /// @brief Get group counts for a specific packed instanced part.
5128 ///
5129 /// @ingroup GeometryGetters
5130 ///
5131 /// @param[in] session
5132 /// The session of Houdini you are interacting with.
5133 /// See @ref HAPI_Sessions for more on sessions.
5134 /// Pass NULL to just use the default in-process session.
5135 /// <!-- default NULL -->
5136 ///
5137 /// @param[in] node_id
5138 /// The node id.
5139 ///
5140 /// @param[in] part_id
5141 /// The part id. (should be a packed primitive)
5142 ///
5143 /// @param[out] pointGroupCount
5144 /// Number of point groups on the packed instance part.
5145 /// Will be set to -1 if the part is not a valid packed part.
5146 ///
5147 /// @param[out] primitiveGroupCount
5148 /// Number of primitive groups on the instanced part.
5149 /// Will be set to -1 if the part is not a valid instancer
5150 ///
5152  HAPI_NodeId node_id,
5153  HAPI_PartId part_id,
5154  int * pointGroupCount,
5155  int * primitiveGroupCount );
5156 
5157 /// @brief Get the group names for a packed instance part
5158 /// This functions allows you to get the group name for a specific
5159 /// packed primitive part.
5160 /// Keep in mind that the name string handles are only
5161 /// valid until the next time this function is called.
5162 ///
5163 /// @ingroup GeometryGetters
5164 ///
5165 /// @param[in] session
5166 /// The session of Houdini you are interacting with.
5167 /// See @ref HAPI_Sessions for more on sessions.
5168 /// Pass NULL to just use the default in-process session.
5169 /// <!-- default NULL -->
5170 ///
5171 /// @param[in] node_id
5172 /// The node id.
5173 ///
5174 /// @param[in] part_id
5175 /// The part id. (should be a packed primitive)
5176 ///
5177 /// @param[in] group_type
5178 /// The group type.
5179 ///
5180 /// @param[out] group_names_array
5181 /// The array of names to be filled. Should be the size
5182 /// given by ::HAPI_GetGroupCountOnPackedInstancePart() with
5183 /// @p group_type and the ::HAPI_PartInfo of @p part_id.
5184 /// @note These string handles are only valid until the
5185 /// next call to ::HAPI_GetGroupNamesOnPackedInstancePart().
5186 ///
5187 /// @param[in] group_count
5188 /// Sanity check. Should be less than or equal to the size
5189 /// of @p group_names.
5190 ///
5192  HAPI_NodeId node_id,
5193  HAPI_PartId part_id,
5194  HAPI_GroupType group_type,
5195  HAPI_StringHandle * group_names_array,
5196  int group_count );
5197 
5198 /// @brief Get group membership for a packed instance part
5199 /// This functions allows you to get the group membership for a specific
5200 /// packed primitive part.
5201 ///
5202 /// @ingroup GeometryGetters
5203 ///
5204 /// @param[in] session
5205 /// The session of Houdini you are interacting with.
5206 /// See @ref HAPI_Sessions for more on sessions.
5207 /// Pass NULL to just use the default in-process session.
5208 /// <!-- default NULL -->
5209 ///
5210 /// @param[in] node_id
5211 /// The node id.
5212 ///
5213 /// @param[in] part_id
5214 /// The part id. (should be a packed primitive)
5215 ///
5216 /// @param[in] group_type
5217 /// The group type.
5218 ///
5219 /// @param[in] group_name
5220 /// The group name.
5221 ///
5222 /// @param[out] membership_array_all_equal
5223 /// (optional) Quick way to determine if all items are in
5224 /// the given group or all items our not in the group.
5225 /// You can just pass NULL here if not interested.
5226 ///
5227 /// @param[out] membership_array
5228 /// Array of ints that represent the membership of this
5229 /// group. Should be the size given by
5230 /// ::HAPI_PartInfo_GetElementCountByGroupType() with
5231 /// @p group_type and the ::HAPI_PartInfo of @p part_id.
5232 ///
5233 /// @param[in] start
5234 /// Start offset into the membership array. Must be
5235 /// less than ::HAPI_PartInfo_GetElementCountByGroupType().
5236 /// <!-- default 0 -->
5237 ///
5238 /// @param[in] length
5239 /// Should be less than or equal to the size
5240 /// of @p membership_array.
5241 /// <!-- source ::HAPI_PartInfo_GetElementCountByGroupType -->
5242 ///
5244  HAPI_NodeId node_id,
5245  HAPI_PartId part_id,
5246  HAPI_GroupType group_type,
5247  const char * group_name,
5248  HAPI_Bool * membership_array_all_equal,
5249  int * membership_array,
5250  int start, int length );
5251 
5252 /// @brief Get the part ids that this instancer part is instancing.
5253 ///
5254 /// @ingroup GeometryGetters
5255 ///
5256 /// @param[in] session
5257 /// The session of Houdini you are interacting with.
5258 /// See @ref HAPI_Sessions for more on sessions.
5259 /// Pass NULL to just use the default in-process session.
5260 /// <!-- default NULL -->
5261 ///
5262 /// @param[in] node_id
5263 /// The node id.
5264 ///
5265 /// @param[in] part_id
5266 /// The instancer part id.
5267 ///
5268 /// @param[out] instanced_parts_array
5269 /// Array of ::HAPI_PartId's to instance.
5270 ///
5271 /// @param[in] start
5272 /// Should be less than @p part_id's
5273 /// ::HAPI_PartInfo::instancedPartCount but more than or
5274 /// equal to 0.
5275 /// <!-- default 0 -->
5276 ///
5277 /// @param[in] length
5278 /// Should be less than @p part_id's
5279 /// ::HAPI_PartInfo::instancedPartCount - @p start.
5280 /// <!-- source ::HAPI_PartInfo::instancedPartCount - start -->
5281 ///
5283  HAPI_NodeId node_id,
5284  HAPI_PartId part_id,
5285  HAPI_PartId * instanced_parts_array,
5286  int start, int length );
5287 
5288 /// @brief Get the instancer part's list of transforms on which to
5289 /// instance the instanced parts you got from
5290 /// ::HAPI_GetInstancedPartIds().
5291 ///
5292 /// @ingroup GeometryGetters
5293 ///
5294 /// @param[in] session
5295 /// The session of Houdini you are interacting with.
5296 /// See @ref HAPI_Sessions for more on sessions.
5297 /// Pass NULL to just use the default in-process session.
5298 /// <!-- default NULL -->
5299 ///
5300 /// @param[in] node_id
5301 /// The node id.
5302 ///
5303 /// @param[in] part_id
5304 /// The instancer part id.
5305 ///
5306 /// @param[in] rst_order
5307 /// The order of application of translation, rotation and
5308 /// scale.
5309 ///
5310 /// @param[out] transforms_array
5311 /// Array of ::HAPI_PartId's to instance.
5312 ///
5313 /// @param[in] start
5314 /// Should be less than @p part_id's
5315 /// ::HAPI_PartInfo::instanceCount but more than or
5316 /// equal to 0.
5317 /// <!-- default 0 -->
5318 ///
5319 /// @param[in] length
5320 /// Should be less than @p part_id's
5321 /// ::HAPI_PartInfo::instanceCount - @p start.
5322 /// <!-- source ::HAPI_PartInfo::instanceCount - start -->
5323 ///
5325  HAPI_NodeId node_id,
5326  HAPI_PartId part_id,
5327  HAPI_RSTOrder rst_order,
5328  HAPI_Transform * transforms_array,
5329  int start, int length );
5330 
5331 /// @defgroup GeometrySetters Geometry Setters
5332 /// Functions for setting geometry (SOP) data
5333 
5334 /// @brief Set the main part info struct (::HAPI_PartInfo).
5335 ///
5336 /// @ingroup GeometrySetters
5337 ///
5338 /// @param[in] session
5339 /// The session of Houdini you are interacting with.
5340 /// See @ref HAPI_Sessions for more on sessions.
5341 /// Pass NULL to just use the default in-process session.
5342 /// <!-- default NULL -->
5343 ///
5344 /// @param[in] node_id
5345 /// The SOP node id.
5346 ///
5347 /// @param[in] part_id
5348 /// Currently not used. Just pass 0.
5349 /// <!-- default 0 -->
5350 ///
5351 /// @param[in] part_info
5352 /// ::HAPI_PartInfo value that describes the input
5353 /// geometry.
5354 ///
5355 HAPI_DECL HAPI_SetPartInfo( const HAPI_Session * session,
5356  HAPI_NodeId node_id,
5357  HAPI_PartId part_id,
5358  const HAPI_PartInfo * part_info );
5359 
5360 /// @brief Set the array of faces where the nth integer in the array is
5361 /// the number of vertices the nth face has.
5362 ///
5363 /// @ingroup GeometrySetters
5364 ///
5365 /// @param[in] session
5366 /// The session of Houdini you are interacting with.
5367 /// See @ref HAPI_Sessions for more on sessions.
5368 /// Pass NULL to just use the default in-process session.
5369 /// <!-- default NULL -->
5370 ///
5371 /// @param[in] node_id
5372 /// The SOP node id.
5373 ///
5374 /// @param[in] part_id
5375 /// Currently not used. Just pass 0.
5376 /// <!-- default 0 -->
5377 ///
5378 /// @param[in] face_counts_array
5379 /// An integer array at least the size of @p length.
5380 ///
5381 /// @param[in] start
5382 /// First index of range. Must be at least 0 and at
5383 /// most ::HAPI_PartInfo::faceCount - 1.
5384 /// <!-- default 0 -->
5385 ///
5386 /// @param[in] length
5387 /// Must be at least 0 and at most
5388 /// ::HAPI_PartInfo::faceCount - @p start.
5389 /// <!-- source ::HAPI_PartInfo::faceCount - start -->
5390 ///
5391 HAPI_DECL HAPI_SetFaceCounts( const HAPI_Session * session,
5392  HAPI_NodeId node_id,
5393  HAPI_PartId part_id,
5394  const int * face_counts_array,
5395  int start, int length );
5396 
5397 /// @brief Set array containing the vertex-point associations where the
5398 /// ith element in the array is the point index the ith vertex
5399 /// associates with.
5400 ///
5401 /// @ingroup GeometrySetters
5402 ///
5403 /// @param[in] session
5404 /// The session of Houdini you are interacting with.
5405 /// See @ref HAPI_Sessions for more on sessions.
5406 /// Pass NULL to just use the default in-process session.
5407 /// <!-- default NULL -->
5408 ///
5409 /// @param[in] node_id
5410 /// The SOP node id.
5411 ///
5412 /// @param[in] part_id
5413 /// Currently not used. Just pass 0.
5414 ///
5415 /// @param[in] vertex_list_array
5416 /// An integer array at least the size of length.
5417 ///
5418 /// @param[in] start
5419 /// First index of range. Must be at least 0 and at
5420 /// most ::HAPI_PartInfo::vertexCount - 1.
5421 /// <!-- default 0 -->
5422 ///
5423 /// @param[in] length
5424 /// Must be at least 0 and at most
5425 /// ::HAPI_PartInfo::vertexCount - @p start.
5426 /// <!-- source ::HAPI_PartInfo::vertexCount - start -->
5427 ///
5428 HAPI_DECL HAPI_SetVertexList( const HAPI_Session * session,
5429  HAPI_NodeId node_id,
5430  HAPI_PartId part_id,
5431  const int * vertex_list_array,
5432  int start, int length );
5433 
5434 /// @brief Add an attribute.
5435 ///
5436 /// @ingroup GeometrySetters
5437 ///
5438 /// @param[in] session
5439 /// The session of Houdini you are interacting with.
5440 /// See @ref HAPI_Sessions for more on sessions.
5441 /// Pass NULL to just use the default in-process session.
5442 /// <!-- default NULL -->
5443 ///
5444 /// @param[in] node_id
5445 /// The SOP node id.
5446 ///
5447 /// @param[in] part_id
5448 /// Currently not used. Just pass 0.
5449 ///
5450 /// @param[in] name
5451 /// Attribute name.
5452 ///
5453 /// @param[in] attr_info
5454 /// ::HAPI_AttributeInfo stores attribute properties.
5455 ///
5456 HAPI_DECL HAPI_AddAttribute( const HAPI_Session * session,
5457  HAPI_NodeId node_id,
5458  HAPI_PartId part_id,
5459  const char * name,
5460  const HAPI_AttributeInfo * attr_info );
5461 /// @brief Delete an attribute from an input geo
5462 ///
5463 /// @ingroup GeometrySetters
5464 ///
5465 /// @param[in] session
5466 /// The session of Houdini you are interacting with.
5467 /// See @ref HAPI_Sessions for more on sessions.
5468 /// Pass NULL to just use the default in-process session.
5469 /// <!-- default NULL -->
5470 ///
5471 /// @param[in] node_id
5472 /// The SOP node id.
5473 ///
5474 /// @param[in] part_id
5475 /// Currently not used. Just pass 0.
5476 ///
5477 /// @param[in] name
5478 /// Attribute name.
5479 ///
5480 /// @param[in] attr_info
5481 /// ::HAPI_AttributeInfo stores attribute properties.
5482 ///
5484  HAPI_NodeId node_id,
5485  HAPI_PartId part_id,
5486  const char * name,
5487  const HAPI_AttributeInfo * attr_info );
5488 
5489 /// @brief Set attribute integer data.
5490 ///
5491 /// @ingroup GeometrySetters
5492 ///
5493 /// @param[in] session
5494 /// The session of Houdini you are interacting with.
5495 /// See @ref HAPI_Sessions for more on sessions.
5496 /// Pass NULL to just use the default in-process session.
5497 /// <!-- default NULL -->
5498 ///
5499 /// @param[in] node_id
5500 /// The SOP node id.
5501 ///
5502 /// @param[in] part_id
5503 /// Currently not used. Just pass 0.
5504 ///
5505 /// @param[in] name
5506 /// Attribute name.
5507 ///
5508 /// @param[in] attr_info
5509 /// ::HAPI_AttributeInfo used as input for what tuple size.
5510 /// you want. Also contains some sanity checks like
5511 /// data type. Generally should be the same struct
5512 /// returned by ::HAPI_GetAttributeInfo().
5513 ///
5514 /// @param[in] data_array
5515 /// An integer array at least the size of
5516 /// <tt>length * ::HAPI_AttributeInfo::tupleSize</tt>.
5517 ///
5518 /// @param[in] start
5519 /// First index of range. Must be at least 0 and at
5520 /// most ::HAPI_AttributeInfo::count - 1.
5521 /// <!-- default 0 -->
5522 ///
5523 /// @param[in] length
5524 /// Must be at least 0 and at most
5525 /// ::HAPI_AttributeInfo::count - @p start.
5526 /// <!-- source ::HAPI_AttributeInfo::count - start -->
5527 ///
5529  HAPI_NodeId node_id,
5530  HAPI_PartId part_id,
5531  const char * name,
5532  const HAPI_AttributeInfo * attr_info,
5533  const int * data_array,
5534  int start, int length );
5535 
5536 /// @brief Set 64-bit attribute integer data.
5537 ///
5538 /// @ingroup GeometrySetters
5539 ///
5540 /// @param[in] session
5541 /// The session of Houdini you are interacting with.
5542 /// See @ref HAPI_Sessions for more on sessions.
5543 /// Pass NULL to just use the default in-process session.
5544 /// <!-- default NULL -->
5545 ///
5546 /// @param[in] node_id
5547 /// The SOP node id.
5548 ///
5549 /// @param[in] part_id
5550 /// Currently not used. Just pass 0.
5551 ///
5552 /// @param[in] name
5553 /// Attribute name.
5554 ///
5555 /// @param[in] attr_info
5556 /// ::HAPI_AttributeInfo used as input for what tuple size.
5557 /// you want. Also contains some sanity checks like
5558 /// data type. Generally should be the same struct
5559 /// returned by ::HAPI_GetAttributeInfo().
5560 ///
5561 /// @param[in] data_array
5562 /// An 64-bit integer array at least the size of
5563 /// <tt>length * ::HAPI_AttributeInfo::tupleSize</tt>.
5564 ///
5565 /// @param[in] start
5566 /// First index of range. Must be at least 0 and at
5567 /// most ::HAPI_AttributeInfo::count - 1.
5568 /// <!-- default 0 -->
5569 ///
5570 /// @param[in] length
5571 /// Must be at least 0 and at most
5572 /// ::HAPI_AttributeInfo::count - @p start.
5573 /// <!-- source ::HAPI_AttributeInfo::count - start -->
5574 ///
5576  HAPI_NodeId node_id,
5577  HAPI_PartId part_id,
5578  const char * name,
5579  const HAPI_AttributeInfo * attr_info,
5580  const HAPI_Int64 * data_array,
5581  int start, int length );
5582 
5583 /// @brief Set attribute float data.
5584 ///
5585 /// @ingroup GeometrySetters
5586 ///
5587 /// @param[in] session
5588 /// The session of Houdini you are interacting with.
5589 /// See @ref HAPI_Sessions for more on sessions.
5590 /// Pass NULL to just use the default in-process session.
5591 /// <!-- default NULL -->
5592 ///
5593 /// @param[in] node_id
5594 /// The SOP node id.
5595 ///
5596 /// @param[in] part_id
5597 /// Currently not used. Just pass 0.
5598 ///
5599 /// @param[in] name
5600 /// Attribute name.
5601 ///
5602 /// @param[in] attr_info
5603 /// ::HAPI_AttributeInfo used as input for what tuple size.
5604 /// you want. Also contains some sanity checks like
5605 /// data type. Generally should be the same struct
5606 /// returned by ::HAPI_GetAttributeInfo().
5607 ///
5608 /// @param[in] data_array
5609 /// An float array at least the size of
5610 /// <tt>length * ::HAPI_AttributeInfo::tupleSize</tt>.
5611 ///
5612 /// @param[in] start
5613 /// First index of range. Must be at least 0 and at
5614 /// most ::HAPI_AttributeInfo::count - 1.
5615 /// <!-- default 0 -->
5616 ///
5617 /// @param[in] length
5618 /// Must be at least 0 and at most
5619 /// ::HAPI_AttributeInfo::count - @p start.
5620 /// <!-- source ::HAPI_AttributeInfo::count - start -->
5621 ///
5623  HAPI_NodeId node_id,
5624  HAPI_PartId part_id,
5625  const char * name,
5626  const HAPI_AttributeInfo * attr_info,
5627  const float * data_array,
5628  int start, int length );
5629 
5630 /// @brief Set 64-bit attribute float data.
5631 ///
5632 /// @ingroup GeometrySetters
5633 ///
5634 /// @param[in] session
5635 /// The session of Houdini you are interacting with.
5636 /// See @ref HAPI_Sessions for more on sessions.
5637 /// Pass NULL to just use the default in-process session.
5638 /// <!-- default NULL -->
5639 ///
5640 /// @param[in] node_id
5641 /// The SOP node id.
5642 ///
5643 /// @param[in] part_id
5644 /// Currently not used. Just pass 0.
5645 ///
5646 /// @param[in] name
5647 /// Attribute name.
5648 ///
5649 /// @param[in] attr_info
5650 /// ::HAPI_AttributeInfo used as input for what tuple size.
5651 /// you want. Also contains some sanity checks like
5652 /// data type. Generally should be the same struct
5653 /// returned by ::HAPI_GetAttributeInfo().
5654 ///
5655 /// @param[in] data_array
5656 /// An 64-bit float array at least the size of
5657 /// <tt>length * ::HAPI_AttributeInfo::tupleSize</tt>.
5658 ///
5659 /// @param[in] start
5660 /// First index of range. Must be at least 0 and at
5661 /// most ::HAPI_AttributeInfo::count - 1.
5662 /// <!-- default 0 -->
5663 ///
5664 /// @param[in] length
5665 /// Must be at least 0 and at most
5666 /// ::HAPI_AttributeInfo::count - @p start.
5667 /// <!-- source ::HAPI_AttributeInfo::count - start -->
5668 ///
5670  HAPI_NodeId node_id,
5671  HAPI_PartId part_id,
5672  const char * name,
5673  const HAPI_AttributeInfo * attr_info,
5674  const double * data_array,
5675  int start, int length );
5676 
5677 /// @brief Set attribute string data.
5678 ///
5679 /// @ingroup GeometrySetters
5680 ///
5681 /// @param[in] session
5682 /// The session of Houdini you are interacting with.
5683 /// See @ref HAPI_Sessions for more on sessions.
5684 /// Pass NULL to just use the default in-process session.
5685 /// <!-- default NULL -->
5686 ///
5687 /// @param[in] node_id
5688 /// The SOP node id.
5689 ///
5690 /// @param[in] part_id
5691 /// Currently not used. Just pass 0.
5692 ///
5693 /// @param[in] name
5694 /// Attribute name.
5695 ///
5696 /// @param[in] attr_info
5697 /// ::HAPI_AttributeInfo used as input for what tuple size.
5698 /// you want. Also contains some sanity checks like
5699 /// data type. Generally should be the same struct
5700 /// returned by ::HAPI_GetAttributeInfo().
5701 ///
5702 /// @param[in] data_array
5703 /// An ::HAPI_StringHandle array at least the size of
5704 /// <tt>length * ::HAPI_AttributeInfo::tupleSize</tt>.
5705 ///
5706 /// @param[in] start
5707 /// First index of range. Must be at least 0 and at
5708 /// most ::HAPI_AttributeInfo::count - 1.
5709 /// <!-- default 0 -->
5710 ///
5711 /// @param[in] length
5712 /// Must be at least 0 and at most
5713 /// ::HAPI_AttributeInfo::count - @p start.
5714 /// <!-- source ::HAPI_AttributeInfo::count - start -->
5715 ///
5717  HAPI_NodeId node_id,
5718  HAPI_PartId part_id,
5719  const char * name,
5720  const HAPI_AttributeInfo * attr_info,
5721  const char ** data_array,
5722  int start, int length );
5723 
5724 /// @brief Add a group to the input geo with the given type and name.
5725 ///
5726 /// @ingroup GeometrySetters
5727 ///
5728 /// @param[in] session
5729 /// The session of Houdini you are interacting with.
5730 /// See @ref HAPI_Sessions for more on sessions.
5731 /// Pass NULL to just use the default in-process session.
5732 /// <!-- default NULL -->
5733 ///
5734 /// @param[in] node_id
5735 /// The SOP node id.
5736 ///
5737 /// @param[in] part_id
5738 /// Currently not used. Just pass 0.
5739 ///
5740 /// @param[in] group_type
5741 /// The group type.
5742 ///
5743 /// @param[in] group_name
5744 /// Name of new group to be added.
5745 ///
5746 HAPI_DECL HAPI_AddGroup( const HAPI_Session * session,
5747  HAPI_NodeId node_id,
5748  HAPI_PartId part_id,
5749  HAPI_GroupType group_type,
5750  const char * group_name );
5751 
5752 /// @brief Remove a group from the input geo with the given type and name.
5753 ///
5754 /// @ingroup GeometrySetters
5755 ///
5756 /// @param[in] session
5757 /// The session of Houdini you are interacting with.
5758 /// See @ref HAPI_Sessions for more on sessions.
5759 /// Pass NULL to just use the default in-process session.
5760 /// <!-- default NULL -->
5761 ///
5762 /// @param[in] node_id
5763 /// The SOP node id.
5764 ///
5765 /// @param[in] part_id
5766 /// Currently not used. Just pass 0.
5767 ///
5768 /// @param[in] group_type
5769 /// The group type.
5770 ///
5771 /// @param[in] group_name
5772 /// Name of the group to be removed
5773 ///
5774 HAPI_DECL HAPI_DeleteGroup( const HAPI_Session * session,
5775  HAPI_NodeId node_id,
5776  HAPI_PartId part_id,
5777  HAPI_GroupType group_type,
5778  const char * group_name );
5779 
5780 /// @brief Set group membership.
5781 ///
5782 /// @ingroup GeometrySetters
5783 ///
5784 /// @param[in] session
5785 /// The session of Houdini you are interacting with.
5786 /// See @ref HAPI_Sessions for more on sessions.
5787 /// Pass NULL to just use the default in-process session.
5788 /// <!-- default NULL -->
5789 ///
5790 /// @param[in] node_id
5791 /// The SOP node id.
5792 ///
5793 /// @param[in] part_id
5794 /// Currently not used. Just pass 0.
5795 /// <!-- default 0 -->
5796 ///
5797 /// @param[in] group_type
5798 /// The group type.
5799 ///
5800 /// @param[in] group_name
5801 /// The group name.
5802 ///
5803 /// @param[in] membership_array
5804 /// Array of ints that represent the membership of this
5805 /// group. Should be the size given by
5806 /// ::HAPI_PartInfo_GetElementCountByGroupType() with
5807 /// @p group_type and the ::HAPI_PartInfo of @p part_id.
5808 ///
5809 /// @param[in] start
5810 /// Start offset into the membership array. Must be
5811 /// less than ::HAPI_PartInfo_GetElementCountByGroupType().
5812 /// <!-- default 0 -->
5813 ///
5814 /// @param[in] length
5815 /// Should be less than or equal to the size
5816 /// of @p membership_array.
5817 /// <!-- source ::HAPI_PartInfo_GetElementCountByGroupType -->
5818 ///
5820  HAPI_NodeId node_id,
5821  HAPI_PartId part_id,
5822  HAPI_GroupType group_type,
5823  const char * group_name,
5824  const int * membership_array,
5825  int start, int length );
5826 
5827 /// @brief Commit the current input geometry to the cook engine. Nodes
5828 /// that use this geometry node will re-cook using the input
5829 /// geometry given through the geometry setter API calls.
5830 ///
5831 /// @ingroup GeometrySetters
5832 ///
5833 /// @param[in] session
5834 /// The session of Houdini you are interacting with.
5835 /// See @ref HAPI_Sessions for more on sessions.
5836 /// Pass NULL to just use the default in-process session.
5837 /// <!-- default NULL -->
5838 ///
5839 /// @param[in] node_id
5840 /// The SOP node id.
5841 ///
5842 HAPI_DECL HAPI_CommitGeo( const HAPI_Session * session,
5843  HAPI_NodeId node_id );
5844 
5845 /// @brief Remove all changes that have been committed to this
5846 /// geometry. If this is an intermediate result node (Edit SOP), all
5847 /// deltas will be removed. If it's any other type of node, the node
5848 /// will be unlocked if it is locked.
5849 ///
5850 /// @ingroup GeometrySetters
5851 ///
5852 /// @param[in] session
5853 /// The session of Houdini you are interacting with.
5854 /// See @ref HAPI_Sessions for more on sessions.
5855 /// Pass NULL to just use the default in-process session.
5856 /// <!-- default NULL -->
5857 ///
5858 /// @param[in] node_id
5859 /// The SOP node id.
5860 ///
5861 HAPI_DECL HAPI_RevertGeo( const HAPI_Session * session,
5862  HAPI_NodeId node_id );
5863 
5864 /// @defgroup Materials
5865 /// Functions for working with materials
5866 
5867 /// @brief Get material ids by face/primitive. The material ids returned
5868 /// will be valid as long as the asset is alive. You should query
5869 /// this list after every cook to see if the material assignments
5870 /// have changed. You should also query each material individually
5871 /// using ::HAPI_GetMaterialInfo() to see if it is dirty and needs
5872 /// to be re-imported.
5873 ///
5874 /// @ingroup Materials
5875 ///
5876 /// @param[in] session
5877 /// The session of Houdini you are interacting with.
5878 /// See @ref HAPI_Sessions for more on sessions.
5879 /// Pass NULL to just use the default in-process session.
5880 /// <!-- default NULL -->
5881 ///
5882 /// @param[in] geometry_node_id
5883 /// The geometry node id.
5884 ///
5885 /// @param[in] part_id
5886 /// The part id.
5887 ///
5888 /// @param[out] are_all_the_same
5889 /// (optional) If true, all faces on this part have the
5890 /// same material assignment. You can pass NULL here.
5891 ///
5892 /// @param[out] material_ids_array
5893 /// An array of ::HAPI_NodeId at least the size of
5894 /// @p length and at most the size of
5895 /// ::HAPI_PartInfo::faceCount.
5896 ///
5897 /// @param[in] start
5898 /// The starting index into the list of faces from which
5899 /// you wish to get the material ids from. Note that
5900 /// this should be less than ::HAPI_PartInfo::faceCount.
5901 /// <!-- default 0 -->
5902 ///
5903 /// @param[in] length
5904 /// The number of material ids you wish to get. Note that
5905 /// this should be at most:
5906 /// ::HAPI_PartInfo::faceCount - @p start.
5907 /// <!-- source ::HAPI_PartInfo::faceCount - start -->
5908 ///
5910  HAPI_NodeId geometry_node_id,
5911  HAPI_PartId part_id,
5912  HAPI_Bool * are_all_the_same,
5913  HAPI_NodeId * material_ids_array,
5914  int start, int length );
5915 
5916 /// @brief Get the material info.
5917 ///
5918 /// @ingroup Materials
5919 ///
5920 /// @param[in] session
5921 /// The session of Houdini you are interacting with.
5922 /// See @ref HAPI_Sessions for more on sessions.
5923 /// Pass NULL to just use the default in-process session.
5924 /// <!-- default NULL -->
5925 ///
5926 /// @param[in] material_node_id
5927 /// The material node id.
5928 ///
5929 /// @param[out] material_info
5930 /// The returned material info.
5931 ///
5933  HAPI_NodeId material_node_id,
5934  HAPI_MaterialInfo * material_info );
5935 
5936 /// @brief Render a single texture from a COP to an image for
5937 /// later extraction.
5938 ///
5939 /// @ingroup Materials
5940 ///
5941 /// Note that you must call this first for any of the other material
5942 /// APIs to work.
5943 ///
5944 /// @param[in] session
5945 /// The session of Houdini you are interacting with.
5946 /// See @ref HAPI_Sessions for more on sessions.
5947 /// Pass NULL to just use the default in-process session.
5948 /// <!-- default NULL -->
5949 ///
5950 /// @param[in] cop_node_id
5951 /// The COP node id.
5952 ///
5954  HAPI_NodeId cop_node_id );
5955 
5956 /// @brief Render only a single texture to an image for later extraction.
5957 /// An example use of this method might be to render the diffuse,
5958 /// normal, and bump texture maps of a material to individual
5959 /// texture files for use within the client application.
5960 ///
5961 /// Note that you must call this first for any of the other material
5962 /// APIs to work.
5963 ///
5964 /// @ingroup Materials
5965 ///
5966 /// @param[in] session
5967 /// The session of Houdini you are interacting with.
5968 /// See @ref HAPI_Sessions for more on sessions.
5969 /// Pass NULL to just use the default in-process session.
5970 /// <!-- default NULL -->
5971 ///
5972 /// @param[in] material_node_id
5973 /// The material node id.
5974 ///
5975 /// @param[in] parm_id
5976 /// This is the index in the parameter list of the
5977 /// material_id's node of the parameter containing the
5978 /// texture map file path.
5979 ///
5981  HAPI_NodeId material_node_id,
5982  HAPI_ParmId parm_id );
5983 
5984 /// @brief Get information about the image that was just rendered, like
5985 /// resolution and default file format. This information will be
5986 /// used when extracting planes to an image.
5987 ///
5988 /// Note that you must call ::HAPI_RenderTextureToImage() first for
5989 /// this method call to make sense.
5990 ///
5991 /// @ingroup Materials
5992 ///
5993 /// @param[in] session
5994 /// The session of Houdini you are interacting with.
5995 /// See @ref HAPI_Sessions for more on sessions.
5996 /// Pass NULL to just use the default in-process session.
5997 /// <!-- default NULL -->
5998 ///
5999 /// @param[in] material_node_id
6000 /// The material node id.
6001 ///
6002 /// @param[out] image_info
6003 /// The struct containing the image information.
6004 ///
6005 HAPI_DECL HAPI_GetImageInfo( const HAPI_Session * session,
6006  HAPI_NodeId material_node_id,
6007  HAPI_ImageInfo * image_info );
6008 
6009 /// @brief Set image information like resolution and file format.
6010 /// This information will be used when extracting planes to
6011 /// an image.
6012 ///
6013 /// Note that you must call ::HAPI_RenderTextureToImage() first for
6014 /// this method call to make sense.
6015 ///
6016 /// You should also first call ::HAPI_GetImageInfo() to get the
6017 /// current Image Info and change only the properties
6018 /// you don't like.
6019 ///
6020 /// @ingroup Materials
6021 ///
6022 /// @param[in] session
6023 /// The session of Houdini you are interacting with.
6024 /// See @ref HAPI_Sessions for more on sessions.
6025 /// Pass NULL to just use the default in-process session.
6026 /// <!-- default NULL -->
6027 ///
6028 /// @param[in] material_node_id
6029 /// The material node id.
6030 ///
6031 /// @param[in] image_info
6032 /// The struct containing the new image information.
6033 ///
6034 HAPI_DECL HAPI_SetImageInfo( const HAPI_Session * session,
6035  HAPI_NodeId material_node_id,
6036  const HAPI_ImageInfo * image_info );
6037 
6038 /// @brief Get the number of image planes for the just rendered image.
6039 ///
6040 /// Note that you must call ::HAPI_RenderTextureToImage() first for
6041 /// this method call to make sense.
6042 ///
6043 /// @ingroup Materials
6044 ///
6045 /// @param[in] session
6046 /// The session of Houdini you are interacting with.
6047 /// See @ref HAPI_Sessions for more on sessions.
6048 /// Pass NULL to just use the default in-process session.
6049 /// <!-- default NULL -->
6050 ///
6051 /// @param[in] material_node_id
6052 /// The material node id.
6053 ///
6054 /// @param[out] image_plane_count
6055 /// The number of image planes.
6056 ///
6058  HAPI_NodeId material_node_id,
6059  int * image_plane_count );
6060 
6061 /// @brief Get the names of the image planes of the just rendered image.
6062 ///
6063 /// Note that you must call ::HAPI_RenderTextureToImage() first for
6064 /// this method call to make sense.
6065 ///
6066 /// You should also call ::HAPI_GetImagePlaneCount() first to get
6067 /// the total number of image planes so you know how large the
6068 /// image_planes string handle array should be.
6069 ///
6070 /// @ingroup Materials
6071 ///
6072 /// @param[in] session
6073 /// The session of Houdini you are interacting with.
6074 /// See @ref HAPI_Sessions for more on sessions.
6075 /// Pass NULL to just use the default in-process session.
6076 /// <!-- default NULL -->
6077 ///
6078 /// @param[in] material_node_id
6079 /// The material node id.
6080 ///
6081 /// @param[out] image_planes_array
6082 /// The image plane names.
6083 ///
6084 /// @param[in] image_plane_count
6085 /// The number of image planes to get names for. This
6086 /// must be less than or equal to the count returned
6087 /// by ::HAPI_GetImagePlaneCount().
6088 /// <!-- source ::HAPI_GetImagePlaneCount -->
6089 ///
6090 HAPI_DECL HAPI_GetImagePlanes( const HAPI_Session * session,
6091  HAPI_NodeId material_node_id,
6092  HAPI_StringHandle * image_planes_array,
6093  int image_plane_count );
6094 
6095 /// @brief Extract a rendered image to a file.
6096 ///
6097 /// Note that you must call ::HAPI_RenderTextureToImage() first for
6098 /// this method call to make sense.
6099 ///
6100 /// @ingroup Materials
6101 ///
6102 /// @param[in] session
6103 /// The session of Houdini you are interacting with.
6104 /// See @ref HAPI_Sessions for more on sessions.
6105 /// Pass NULL to just use the default in-process session.
6106 /// <!-- default NULL -->
6107 ///
6108 /// @param[in] material_node_id
6109 /// The material node id.
6110 ///
6111 /// @param[in] image_file_format_name
6112 /// The image file format name you wish the image to be
6113 /// extracted as. You can leave this parameter NULL to
6114 /// get the image in the original format if it comes from
6115 /// another texture file or in the default HAPI format,
6116 /// which is ::HAPI_DEFAULT_IMAGE_FORMAT_NAME, if the image
6117 /// is generated.
6118 ///
6119 /// You can get some of the very common standard image
6120 /// file format names from HAPI_Common.h under the
6121 /// "Defines" section.
6122 ///
6123 /// You can also get a list of all supported file formats
6124 /// (and the exact names this parameter expects)
6125 /// by using ::HAPI_GetSupportedImageFileFormats(). This
6126 /// list will include custom file formats you created via
6127 /// custom DSOs (see HDK docs about IMG_Format). You will
6128 /// get back a list of ::HAPI_ImageFileFormat. This
6129 /// parameter expects the ::HAPI_ImageFileFormat::nameSH
6130 /// of a given image file format.
6131 ///
6132 /// @param[in] image_planes
6133 /// The image planes you wish to extract into the file.
6134 /// Multiple image planes should be separated by spaces.
6135 ///
6136 /// @param[in] destination_folder_path
6137 /// The folder where the image file should be created.
6138 ///
6139 /// @param[in] destination_file_name
6140 /// Optional parameter to overwrite the name of the
6141 /// extracted texture file. This should NOT include
6142 /// the extension as the file type will be decided
6143 /// by the ::HAPI_ImageInfo you can set using
6144 /// ::HAPI_SetImageInfo(). You still have to use
6145 /// destination_file_path to get the final file path.
6146 ///
6147 /// Pass in NULL to have the file name be automatically
6148 /// generated from the name of the material SHOP node,
6149 /// the name of the texture map parameter if the
6150 /// image was rendered from a texture, and the image
6151 /// plane names specified.
6152 ///
6153 /// @param[out] destination_file_path
6154 /// The full path string handle, including the
6155 /// destination_folder_path and the texture file name,
6156 /// to the extracted file. Note that this string handle
6157 /// will only be valid until the next call to
6158 /// this function.
6159 ///
6161  HAPI_NodeId material_node_id,
6162  const char * image_file_format_name,
6163  const char * image_planes,
6164  const char * destination_folder_path,
6165  const char * destination_file_name,
6166  int * destination_file_path );
6167 /// @brief Get the file name that this image would be saved to
6168 ///
6169 /// Check to see what file path HAPI_ExtractImageToFile would have
6170 /// saved to given the same parms. Perhaps you might wish to see
6171 /// if it already exists before extracting.
6172 ///
6173 /// @ingroup Materials
6174 ///
6175 /// @param[in] session
6176 /// The session of Houdini you are interacting with.
6177 /// See @ref HAPI_Sessions for more on sessions.
6178 /// Pass NULL to just use the default in-process session.
6179 /// <!-- default NULL -->
6180 ///
6181 /// @param[in] material_node_id
6182 /// The material node id.
6183 ///
6184 /// @param[in] image_file_format_name
6185 /// The image file format name you wish the image to be
6186 /// extracted as. See HAPI_ExtractImageToFile for more information.
6187 ///
6188 /// @param[in] image_planes
6189 /// The image planes you wish to extract into the file.
6190 /// Multiple image planes should be separated by spaces.
6191 ///
6192 /// @param[in] destination_folder_path
6193 /// The folder where the image file sould be created.
6194 ///
6195 /// @param[in] destination_file_name
6196 /// Optional parameter to overwrite the name of the
6197 /// extracted texture file. See HAPI_ExtractImageToFile for more information.
6198 ///
6199 /// @param[in] texture_parm_id
6200 /// The index in the parameter list of the material node.
6201 /// of the parameter containing the texture map file path
6202 ///
6203 /// @param[out] destination_file_path
6204 /// The full path string handle, including the
6205 /// destination_folder_path and the texture file name,
6206 /// to the extracted file. Note that this string handle
6207 /// will only be valid until the next call to
6208 /// this function.
6209 ///
6211  HAPI_NodeId material_node_id,
6212  const char * image_file_format_name,
6213  const char * image_planes,
6214  const char * destination_folder_path,
6215  const char * destination_file_name,
6216  HAPI_ParmId texture_parm_id,
6217  int * destination_file_path );
6218 
6219 /// @brief Extract a rendered image to memory.
6220 ///
6221 /// Note that you must call ::HAPI_RenderTextureToImage() first for
6222 /// this method call to make sense.
6223 ///
6224 /// Also note that this function will do all the work of
6225 /// extracting and compositing the image into a memory buffer
6226 /// but will not return to you that buffer, only its size. Use
6227 /// the returned size to allocated a sufficiently large buffer
6228 /// and call ::HAPI_GetImageMemoryBuffer() to fill your buffer
6229 /// with the just extracted image.
6230 ///
6231 /// @ingroup Materials
6232 ///
6233 /// @param[in] session
6234 /// The session of Houdini you are interacting with.
6235 /// See @ref HAPI_Sessions for more on sessions.
6236 /// Pass NULL to just use the default in-process session.
6237 /// <!-- default NULL -->
6238 ///
6239 /// @param[in] material_node_id
6240 /// The material node id.
6241 ///
6242 /// @param[in] image_file_format_name
6243 /// The image file format name you wish the image to be
6244 /// extracted as. You can leave this parameter NULL to
6245 /// get the image in the original format if it comes from
6246 /// another texture file or in the default HAPI format,
6247 /// which is ::HAPI_DEFAULT_IMAGE_FORMAT_NAME, if the image
6248 /// is generated.
6249 ///
6250 /// You can get some of the very common standard image
6251 /// file format names from HAPI_Common.h under the
6252 /// "Defines" section.
6253 ///
6254 /// You can also get a list of all supported file formats
6255 /// (and the exact names this parameter expects)
6256 /// by using ::HAPI_GetSupportedImageFileFormats(). This
6257 /// list will include custom file formats you created via
6258 /// custom DSOs (see HDK docs about IMG_Format). You will
6259 /// get back a list of ::HAPI_ImageFileFormat. This
6260 /// parameter expects the ::HAPI_ImageFileFormat::nameSH
6261 /// of a given image file format.
6262 ///
6263 /// @param[in] image_planes
6264 /// The image planes you wish to extract into the file.
6265 /// Multiple image planes should be separated by spaces.
6266 ///
6267 /// @param[out] buffer_size
6268 /// The extraction will be done to an internal buffer
6269 /// who's size you get via this parameter. Use the
6270 /// returned buffer_size when calling
6271 /// ::HAPI_GetImageMemoryBuffer() to get the image
6272 /// buffer you just extracted.
6273 ///
6275  HAPI_NodeId material_node_id,
6276  const char * image_file_format_name,
6277  const char * image_planes,
6278  int * buffer_size );
6279 
6280 /// @brief Fill your allocated buffer with the just extracted
6281 /// image buffer.
6282 ///
6283 /// Note that you must call ::HAPI_RenderTextureToImage() first for
6284 /// this method call to make sense.
6285 ///
6286 /// Also note that you must call ::HAPI_ExtractImageToMemory()
6287 /// first in order to perform the extraction and get the
6288 /// extracted image buffer size that you need to know how much
6289 /// memory to allocated to fit your extracted image.
6290 ///
6291 /// @ingroup Materials
6292 ///
6293 /// @param[in] session
6294 /// The session of Houdini you are interacting with.
6295 /// See @ref HAPI_Sessions for more on sessions.
6296 /// Pass NULL to just use the default in-process session.
6297 /// <!-- default NULL -->
6298 ///
6299 /// @param[in] material_node_id
6300 /// The material node id.
6301 ///
6302 /// @param[out] buffer
6303 /// The buffer passed in here will be filled with the
6304