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
Add $HFS/bin to the Windows $PATH variable.
API Overview
This crates tries hard to be nice and 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,
HAPI_INPUT_TRANSFORM,
HAPI_INPUT_GEOMETRY,
HAPI_INPUT_MAX
};
// This crate's enum
enum InputType {
Invalid = -1,
Transform = 0,
Geometry = 1,
Max = 2
}
Some underlying 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 and minimizing noise.
Structs that you do need ability to create, implement Default and follow the 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 Optioncontext
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 return CString or String. See the stringhandle
module for more info.