Expand description
§Rust bindings to Houdini Engine C API.
Official HAPI documentation:
Check out the examples:
cargo run --example ...
§Building and running
HFS environment variable must be set for the build script to link to Houdini libraries.
For runtime discovery of Houdini libraries there are several options:
§Mac & Linux
Option 1
Build with RPATH via the RUSTFLAGS variable:
RUSTFLAGS="-C link-args=-Wl,-rpath,/path/to/hfs/dsolib" cargo build
Option 2
Add a cargo config file to your project: .cargo/config
[target.'cfg(target_os = "linux")']
rustflags = ["-C", "link-arg=-Wl,-rpath=/opt/hfs/19.5.368/dsolib"]
[target.x86_64-apple-darwin]
rustflags = ["-C",
"link-arg=-Wl,-rpath,/Applications/Houdini/Current/Frameworks/Houdini.framework/Versions/Current/Libraries",
]
Option 3
At runtime via env variables: $LD_LIBRARY_PATH
on Linux and $DYLD_LIBRARY_PATH
on MacOS
§Windows
$HFS
variable must be set for building.
Runtime Houdini libraries are required to be in $PATH: Add $HFS/bin to $PATH.
§API Overview
This crates aims to be easy to use, hiding the inconvenient C API as much as possible
while also trying to keep function names clear and close to original.
To archive this, the crate wraps every single C struct in a new struct and provide getters/setters for its fields.
All structs and enums have their HAPI_
prefix removed.
In addition all enum variants are shortened. For example:
// Original struct:
struct HAPI_NodeInfo {
pub parmCount: ::std::os::raw::c_int,
...
}
// This crate's struct:
let info: crate::node::NodeInfo;
let count: i32 = info.parm_count();
// Original enum (C)
enum HAPI_InputType {
HAPI_INPUT_INVALID = -1,
...
};
// This crate's enum
enum InputType {
Invalid = -1,
...
}
Some underlying C structs don’t provide a direct way of creating them or they might not provide methods
for modifying them, due to this crate’s attempt for proper data encapsulation, minimizing noise and improving safety.
Structs that you do need the ability to create, implement Default and some a Builder Pattern
with convenient with_
and set_
methods:
let part_info = PartInfo::default()
.with_part_type(PartType::Mesh)
.with_face_count(6);
§Error type
All API calls return HapiError
(HAPI_Result)
In case of error, the HapiError struct contains an Option<String>
with an error message returned from the Engine.
Additional error context is available in the contexts
field of the error type.
§Strings
Houdini Engine being C API, makes life a little harder for Rust programmer when it comes to strings. The crate chose to accept some overhead related to string conversion in exchange for a nicer API and easy of use.
For example getting/setting a parameter value will perform a conversion CString <-> String, but not in every situation such conversion is acceptable, for example reading geometry string attributes can be very expensive since we have do potentially thousands of CString to String conversions.
To aid this situation, the crate provides custom structs which implement different iterators,
which yield CString or String types. See the stringhandle
module for more info.
§Nodes
node::NodeHandle
is lightweight handle to a Houdini node, it’s returned by some APIs and can not
be created by the users. The node::NodeHandle
has a limited functionality because it doesn’t hold
a pointer to the session::Session
.
node::HoudiniNode
is the main type which combines node::NodeHandle
, node::NodeInfo
and session::Session
types into a single struct which exports most of the node APIs.
Some APIs choose to return a lightweight node::NodeHandle
that can be simply passed to other APIs.
You can upgrade the handle to a full node by node::NodeHandle::to_node
to get access to full node API.
Due to HAPI only exposes a limited subset of APIs to Houdini, and to keep things simple,
there no different flavors of node::HoudiniNode
.
Instead this type provides the common node APIs and some node-type-specific APIs are available
in separate types like pdg::TopNode
and geometry::Geometry
which hold node::HoudiniNode
as a struct field (composition vs inheritance).
§Parameters
Parameters are modelled with parameter::Parameter
enum that contains different parameter types.
Common parameter methods are provided in parameter::ParmBaseTrait
.
Modules§
- For loading digital assets and reading their parameters. Documentation
- Geometry attributes access and iterators
- All Engine API enums are here
- Access to geometry data, attributes, reading and writing geometry to and from disk
- Rendering material textures to memory or disk
- Manipulating Houdini nodes and networks, getting geometry and parameters
- Reading and setting node parameters, setting expressions and keyframes.
- Session is responsible for communicating with HAPI
- String handling utilities and iterators
- Volume and Heightfield APIs
Structs§
- Engine version this library was build upon
- Error type returned by all APIs
- Houdini version this library was build upon
Constants§
- Engine version this library was build upon
- Houdini version this library was build upon