MeshLib C Docs
Loading...
Searching...
No Matches
MRSweptVolume.h File Reference
#include <MRCMesh/MRBox.h>
#include <MRCMisc/common.h>
#include <MRCMisc/exports.h>
#include <stddef.h>

Go to the source code of this file.

Typedefs

typedef struct MR_EndMillTool MR_EndMillTool
 
typedef struct MR_MeshPart MR_MeshPart
 
typedef struct MR_Polyline2 MR_Polyline2
 
typedef struct MR_Polyline3 MR_Polyline3
 
typedef struct MR_Vector3f MR_Vector3f
 
typedef struct MR_Vector3i MR_Vector3i
 
typedef struct MR_expected_MR_Mesh_std_string MR_expected_MR_Mesh_std_string
 
typedef struct MR_expected_MR_Vector3i_std_string MR_expected_MR_Vector3i_std_string
 
typedef struct MR_expected_void_std_string MR_expected_void_std_string
 
typedef struct MR_std_function_bool_from_float MR_std_function_bool_from_float
 
typedef struct MR_std_vector_float MR_std_vector_float
 
typedef struct MR_ComputeSweptVolumeParameters MR_ComputeSweptVolumeParameters
 
typedef struct MR_IComputeToolDistance MR_IComputeToolDistance
 

Functions

MRC_API MR_Box3f MR_computeWorkArea (const MR_Polyline3 *toolpath, const MR_MeshPart *tool)
 
MRC_API MR_Box3i MR_computeGridBox (const MR_Box3f *workArea, float voxelSize)
 
MRC_API const MR_Polyline3MR_ComputeSweptVolumeParameters_Get_path (const MR_ComputeSweptVolumeParameters *_this)
 
MRC_API const MR_MeshPartMR_ComputeSweptVolumeParameters_Get_toolMesh (const MR_ComputeSweptVolumeParameters *_this)
 
MRC_API MR_MeshPartMR_ComputeSweptVolumeParameters_GetMutable_toolMesh (MR_ComputeSweptVolumeParameters *_this)
 
MRC_API const MR_EndMillTool *const * MR_ComputeSweptVolumeParameters_Get_toolSpec (const MR_ComputeSweptVolumeParameters *_this)
 
MRC_API void MR_ComputeSweptVolumeParameters_Set_toolSpec (MR_ComputeSweptVolumeParameters *_this, const MR_EndMillTool *value)
 
MRC_API const MR_EndMillTool ** MR_ComputeSweptVolumeParameters_GetMutable_toolSpec (MR_ComputeSweptVolumeParameters *_this)
 
MRC_API const float * MR_ComputeSweptVolumeParameters_Get_voxelSize (const MR_ComputeSweptVolumeParameters *_this)
 voxel size for internal voxel volumes
 
MRC_API void MR_ComputeSweptVolumeParameters_Set_voxelSize (MR_ComputeSweptVolumeParameters *_this, float value)
 voxel size for internal voxel volumes
 
MRC_API float * MR_ComputeSweptVolumeParameters_GetMutable_voxelSize (MR_ComputeSweptVolumeParameters *_this)
 voxel size for internal voxel volumes
 
MRC_API const MR_uint64_tMR_ComputeSweptVolumeParameters_Get_memoryLimit (const MR_ComputeSweptVolumeParameters *_this)
 
MRC_API void MR_ComputeSweptVolumeParameters_Set_memoryLimit (MR_ComputeSweptVolumeParameters *_this, MR_uint64_t value)
 
MRC_API MR_uint64_tMR_ComputeSweptVolumeParameters_GetMutable_memoryLimit (MR_ComputeSweptVolumeParameters *_this)
 
MRC_API const MR_std_function_bool_from_floatMR_ComputeSweptVolumeParameters_Get_cb (const MR_ComputeSweptVolumeParameters *_this)
 
MRC_API void MR_ComputeSweptVolumeParameters_Set_cb (MR_ComputeSweptVolumeParameters *_this, MR_PassBy value_pass_by, MR_std_function_bool_from_float *value)
 
MRC_API MR_std_function_bool_from_floatMR_ComputeSweptVolumeParameters_GetMutable_cb (MR_ComputeSweptVolumeParameters *_this)
 
MRC_API MR_ComputeSweptVolumeParametersMR_ComputeSweptVolumeParameters_ConstructFromAnother (MR_PassBy _other_pass_by, MR_ComputeSweptVolumeParameters *_other)
 
MRC_API MR_ComputeSweptVolumeParametersMR_ComputeSweptVolumeParameters_ConstructFrom (const MR_Polyline3 *path, const MR_MeshPart *toolMesh, const MR_EndMillTool *toolSpec, float voxelSize, MR_uint64_t memoryLimit, MR_PassBy cb_pass_by, MR_std_function_bool_from_float *cb)
 
MRC_API const MR_ComputeSweptVolumeParametersMR_ComputeSweptVolumeParameters_OffsetPtr (const MR_ComputeSweptVolumeParameters *ptr, ptrdiff_t i)
 Offsets a pointer to an array element by i positions (not bytes). Use only if you're certain that the pointer points to an array element.
 
MRC_API MR_ComputeSweptVolumeParametersMR_ComputeSweptVolumeParameters_OffsetMutablePtr (MR_ComputeSweptVolumeParameters *ptr, ptrdiff_t i)
 Offsets a pointer to an array element by i positions (not bytes). Use only if you're certain that the pointer points to an array element.
 
MRC_API void MR_ComputeSweptVolumeParameters_Destroy (const MR_ComputeSweptVolumeParameters *_this)
 Destroys a heap-allocated instance of MR_ComputeSweptVolumeParameters. Does nothing if the pointer is null.
 
MRC_API void MR_ComputeSweptVolumeParameters_DestroyArray (const MR_ComputeSweptVolumeParameters *_this)
 Destroys a heap-allocated array of MR_ComputeSweptVolumeParameters. Does nothing if the pointer is null.
 
MRC_API MR_expected_MR_Mesh_std_stringMR_computeSweptVolumeWithMeshMovement (const MR_ComputeSweptVolumeParameters *params)
 
MRC_API MR_expected_MR_Mesh_std_stringMR_computeSweptVolumeWithDistanceVolume (const MR_ComputeSweptVolumeParameters *params)
 
MRC_API void MR_IComputeToolDistance_Destroy (const MR_IComputeToolDistance *_this)
 Destroys a heap-allocated instance of MR_IComputeToolDistance. Does nothing if the pointer is null.
 
MRC_API void MR_IComputeToolDistance_DestroyArray (const MR_IComputeToolDistance *_this)
 Destroys a heap-allocated array of MR_IComputeToolDistance. Does nothing if the pointer is null.
 
MRC_API MR_expected_MR_Vector3i_std_stringMR_IComputeToolDistance_prepare_MR_EndMillTool (MR_IComputeToolDistance *_this, const MR_Vector3i *dims, const MR_Polyline3 *toolpath, const MR_EndMillTool *toolSpec)
 
MRC_API MR_expected_MR_Vector3i_std_stringMR_IComputeToolDistance_prepare_MR_Polyline2 (MR_IComputeToolDistance *_this, const MR_Vector3i *dims, const MR_Polyline3 *toolpath, const MR_Polyline2 *toolProfile)
 
MRC_API MR_expected_void_std_stringMR_IComputeToolDistance_computeToolDistance (const MR_IComputeToolDistance *_this, MR_std_vector_float *output, const MR_Vector3i *dims, float voxelSize, const MR_Vector3f *origin, float padding)
 
MRC_API const MR_IComputeToolDistanceMR_IComputeToolDistance_OffsetPtr (const MR_IComputeToolDistance *ptr, ptrdiff_t i)
 Offsets a pointer to an array element by i positions (not bytes). Use only if you're certain that the pointer points to an array element.
 
MRC_API MR_IComputeToolDistanceMR_IComputeToolDistance_OffsetMutablePtr (MR_IComputeToolDistance *ptr, ptrdiff_t i)
 Offsets a pointer to an array element by i positions (not bytes). Use only if you're certain that the pointer points to an array element.
 
MRC_API MR_expected_MR_Mesh_std_stringMR_computeSweptVolumeWithCustomToolDistance (MR_IComputeToolDistance *comp, const MR_ComputeSweptVolumeParameters *params)
 

Typedef Documentation

◆ MR_ComputeSweptVolumeParameters

Parameters for computeSweptVolume* functions Generated from class MR::ComputeSweptVolumeParameters.

◆ MR_EndMillTool

◆ MR_expected_MR_Mesh_std_string

◆ MR_expected_MR_Vector3i_std_string

◆ MR_expected_void_std_string

◆ MR_IComputeToolDistance

Interface for custom tool distance computation implementations Generated from class MR::IComputeToolDistance.

◆ MR_MeshPart

typedef struct MR_MeshPart MR_MeshPart

◆ MR_Polyline2

typedef struct MR_Polyline2 MR_Polyline2

◆ MR_Polyline3

typedef struct MR_Polyline3 MR_Polyline3

◆ MR_std_function_bool_from_float

◆ MR_std_vector_float

◆ MR_Vector3f

typedef struct MR_Vector3f MR_Vector3f

◆ MR_Vector3i

typedef struct MR_Vector3i MR_Vector3i

Function Documentation

◆ MR_computeGridBox()

MRC_API MR_Box3i MR_computeGridBox ( const MR_Box3f * workArea,
float voxelSize )

Compute required voxel volume's dimensions for given work area Generated from function MR::computeGridBox. Parameter workArea can not be null. It is a single object.

◆ MR_ComputeSweptVolumeParameters_ConstructFrom()

MRC_API MR_ComputeSweptVolumeParameters * MR_ComputeSweptVolumeParameters_ConstructFrom ( const MR_Polyline3 * path,
const MR_MeshPart * toolMesh,
const MR_EndMillTool * toolSpec,
float voxelSize,
MR_uint64_t memoryLimit,
MR_PassBy cb_pass_by,
MR_std_function_bool_from_float * cb )

Constructs MR::ComputeSweptVolumeParameters elementwise. Parameter path can not be null. It is a single object. Parameter toolMesh can not be null. It is a single object. Never returns null. Returns an instance allocated on the heap! Must call MR_ComputeSweptVolumeParameters_Destroy() to free it when you're done using it.

◆ MR_ComputeSweptVolumeParameters_ConstructFromAnother()

MRC_API MR_ComputeSweptVolumeParameters * MR_ComputeSweptVolumeParameters_ConstructFromAnother ( MR_PassBy _other_pass_by,
MR_ComputeSweptVolumeParameters * _other )

Generated from a constructor of class MR::ComputeSweptVolumeParameters. Never returns null. Returns an instance allocated on the heap! Must call MR_ComputeSweptVolumeParameters_Destroy() to free it when you're done using it.

◆ MR_ComputeSweptVolumeParameters_Destroy()

MRC_API void MR_ComputeSweptVolumeParameters_Destroy ( const MR_ComputeSweptVolumeParameters * _this)

Destroys a heap-allocated instance of MR_ComputeSweptVolumeParameters. Does nothing if the pointer is null.

◆ MR_ComputeSweptVolumeParameters_DestroyArray()

MRC_API void MR_ComputeSweptVolumeParameters_DestroyArray ( const MR_ComputeSweptVolumeParameters * _this)

Destroys a heap-allocated array of MR_ComputeSweptVolumeParameters. Does nothing if the pointer is null.

◆ MR_ComputeSweptVolumeParameters_Get_cb()

MRC_API const MR_std_function_bool_from_float * MR_ComputeSweptVolumeParameters_Get_cb ( const MR_ComputeSweptVolumeParameters * _this)

progress callback Returns a pointer to a member variable of class MR::ComputeSweptVolumeParameters named cb. Parameter _this can not be null. It is a single object. The returned pointer will never be null. It is non-owning, do NOT destroy it.

◆ MR_ComputeSweptVolumeParameters_Get_memoryLimit()

MRC_API const MR_uint64_t * MR_ComputeSweptVolumeParameters_Get_memoryLimit ( const MR_ComputeSweptVolumeParameters * _this)

(distance volume) max memory amount used for the distance volume, zero for no limits Returns a pointer to a member variable of class MR::ComputeSweptVolumeParameters named memoryLimit. Parameter _this can not be null. It is a single object. The returned pointer will never be null. It is non-owning, do NOT destroy it.

◆ MR_ComputeSweptVolumeParameters_Get_path()

MRC_API const MR_Polyline3 * MR_ComputeSweptVolumeParameters_Get_path ( const MR_ComputeSweptVolumeParameters * _this)

toolpath Returns a pointer to a member variable of class MR::ComputeSweptVolumeParameters named path. Parameter _this can not be null. It is a single object. The returned pointer will never be null. It is non-owning, do NOT destroy it.

◆ MR_ComputeSweptVolumeParameters_Get_toolMesh()

MRC_API const MR_MeshPart * MR_ComputeSweptVolumeParameters_Get_toolMesh ( const MR_ComputeSweptVolumeParameters * _this)

tool mesh Returns a pointer to a member variable of class MR::ComputeSweptVolumeParameters named toolMesh. Parameter _this can not be null. It is a single object. The returned pointer will never be null. It is non-owning, do NOT destroy it.

◆ MR_ComputeSweptVolumeParameters_Get_toolSpec()

MRC_API const MR_EndMillTool *const * MR_ComputeSweptVolumeParameters_Get_toolSpec ( const MR_ComputeSweptVolumeParameters * _this)

tool specifications, can be used for more precise computations the tool spec and the tool mesh are expected to relate to the same tool if omitted, tool mesh is used Returns a pointer to a member variable of class MR::ComputeSweptVolumeParameters named toolSpec. Parameter _this can not be null. It is a single object. The returned pointer will never be null. It is non-owning, do NOT destroy it.

◆ MR_ComputeSweptVolumeParameters_Get_voxelSize()

MRC_API const float * MR_ComputeSweptVolumeParameters_Get_voxelSize ( const MR_ComputeSweptVolumeParameters * _this)

voxel size for internal voxel volumes

Returns a pointer to a member variable of class MR::ComputeSweptVolumeParameters named voxelSize. Parameter _this can not be null. It is a single object. The returned pointer will never be null. It is non-owning, do NOT destroy it.

◆ MR_ComputeSweptVolumeParameters_GetMutable_cb()

MRC_API MR_std_function_bool_from_float * MR_ComputeSweptVolumeParameters_GetMutable_cb ( MR_ComputeSweptVolumeParameters * _this)

progress callback Returns a mutable pointer to a member variable of class MR::ComputeSweptVolumeParameters named cb. Parameter _this can not be null. It is a single object. The returned pointer will never be null. It is non-owning, do NOT destroy it.

◆ MR_ComputeSweptVolumeParameters_GetMutable_memoryLimit()

MRC_API MR_uint64_t * MR_ComputeSweptVolumeParameters_GetMutable_memoryLimit ( MR_ComputeSweptVolumeParameters * _this)

(distance volume) max memory amount used for the distance volume, zero for no limits Returns a mutable pointer to a member variable of class MR::ComputeSweptVolumeParameters named memoryLimit. Parameter _this can not be null. It is a single object. The returned pointer will never be null. It is non-owning, do NOT destroy it.

◆ MR_ComputeSweptVolumeParameters_GetMutable_toolMesh()

MRC_API MR_MeshPart * MR_ComputeSweptVolumeParameters_GetMutable_toolMesh ( MR_ComputeSweptVolumeParameters * _this)

tool mesh Returns a mutable pointer to a member variable of class MR::ComputeSweptVolumeParameters named toolMesh. Parameter _this can not be null. It is a single object. The returned pointer will never be null. It is non-owning, do NOT destroy it.

◆ MR_ComputeSweptVolumeParameters_GetMutable_toolSpec()

MRC_API const MR_EndMillTool ** MR_ComputeSweptVolumeParameters_GetMutable_toolSpec ( MR_ComputeSweptVolumeParameters * _this)

tool specifications, can be used for more precise computations the tool spec and the tool mesh are expected to relate to the same tool if omitted, tool mesh is used Returns a mutable pointer to a member variable of class MR::ComputeSweptVolumeParameters named toolSpec. Parameter _this can not be null. It is a single object. The returned pointer will never be null. It is non-owning, do NOT destroy it.

◆ MR_ComputeSweptVolumeParameters_GetMutable_voxelSize()

MRC_API float * MR_ComputeSweptVolumeParameters_GetMutable_voxelSize ( MR_ComputeSweptVolumeParameters * _this)

voxel size for internal voxel volumes

Returns a mutable pointer to a member variable of class MR::ComputeSweptVolumeParameters named voxelSize. Parameter _this can not be null. It is a single object. The returned pointer will never be null. It is non-owning, do NOT destroy it.

◆ MR_ComputeSweptVolumeParameters_OffsetMutablePtr()

MRC_API MR_ComputeSweptVolumeParameters * MR_ComputeSweptVolumeParameters_OffsetMutablePtr ( MR_ComputeSweptVolumeParameters * ptr,
ptrdiff_t i )

Offsets a pointer to an array element by i positions (not bytes). Use only if you're certain that the pointer points to an array element.

◆ MR_ComputeSweptVolumeParameters_OffsetPtr()

MRC_API const MR_ComputeSweptVolumeParameters * MR_ComputeSweptVolumeParameters_OffsetPtr ( const MR_ComputeSweptVolumeParameters * ptr,
ptrdiff_t i )

Offsets a pointer to an array element by i positions (not bytes). Use only if you're certain that the pointer points to an array element.

◆ MR_ComputeSweptVolumeParameters_Set_cb()

MRC_API void MR_ComputeSweptVolumeParameters_Set_cb ( MR_ComputeSweptVolumeParameters * _this,
MR_PassBy value_pass_by,
MR_std_function_bool_from_float * value )

progress callback Modifies a member variable of class MR::ComputeSweptVolumeParameters named cb. Parameter _this can not be null. It is a single object.

◆ MR_ComputeSweptVolumeParameters_Set_memoryLimit()

MRC_API void MR_ComputeSweptVolumeParameters_Set_memoryLimit ( MR_ComputeSweptVolumeParameters * _this,
MR_uint64_t value )

(distance volume) max memory amount used for the distance volume, zero for no limits Modifies a member variable of class MR::ComputeSweptVolumeParameters named memoryLimit. Parameter _this can not be null. It is a single object.

◆ MR_ComputeSweptVolumeParameters_Set_toolSpec()

MRC_API void MR_ComputeSweptVolumeParameters_Set_toolSpec ( MR_ComputeSweptVolumeParameters * _this,
const MR_EndMillTool * value )

tool specifications, can be used for more precise computations the tool spec and the tool mesh are expected to relate to the same tool if omitted, tool mesh is used Modifies a member variable of class MR::ComputeSweptVolumeParameters named toolSpec. Parameter _this can not be null. It is a single object.

◆ MR_ComputeSweptVolumeParameters_Set_voxelSize()

MRC_API void MR_ComputeSweptVolumeParameters_Set_voxelSize ( MR_ComputeSweptVolumeParameters * _this,
float value )

voxel size for internal voxel volumes

Modifies a member variable of class MR::ComputeSweptVolumeParameters named voxelSize. Parameter _this can not be null. It is a single object.

◆ MR_computeSweptVolumeWithCustomToolDistance()

MRC_API MR_expected_MR_Mesh_std_string * MR_computeSweptVolumeWithCustomToolDistance ( MR_IComputeToolDistance * comp,
const MR_ComputeSweptVolumeParameters * params )

Compute swept volume for given toolpath and tool Creates a distance-to-tool volume using custom tool distance computation object and converts it to mesh using the marching cubes algorithm Generated from function MR::computeSweptVolumeWithCustomToolDistance. Parameter comp can not be null. It is a single object. Parameter params can not be null. It is a single object. Never returns null. Returns an instance allocated on the heap! Must call MR_expected_MR_Mesh_std_string_Destroy() to free it when you're done using it.

◆ MR_computeSweptVolumeWithDistanceVolume()

MRC_API MR_expected_MR_Mesh_std_string * MR_computeSweptVolumeWithDistanceVolume ( const MR_ComputeSweptVolumeParameters * params)

Compute swept volume for given toolpath and tool Creates a distance-to-tool volume and converts it to mesh using the marching cubes algorithm Generated from function MR::computeSweptVolumeWithDistanceVolume. Parameter params can not be null. It is a single object. Never returns null. Returns an instance allocated on the heap! Must call MR_expected_MR_Mesh_std_string_Destroy() to free it when you're done using it.

◆ MR_computeSweptVolumeWithMeshMovement()

MRC_API MR_expected_MR_Mesh_std_string * MR_computeSweptVolumeWithMeshMovement ( const MR_ComputeSweptVolumeParameters * params)

Compute swept volume for given toolpath and tool Builds mesh for each tool movement and joins them using voxel boolean Generated from function MR::computeSweptVolumeWithMeshMovement. Parameter params can not be null. It is a single object. Never returns null. Returns an instance allocated on the heap! Must call MR_expected_MR_Mesh_std_string_Destroy() to free it when you're done using it.

◆ MR_computeWorkArea()

MRC_API MR_Box3f MR_computeWorkArea ( const MR_Polyline3 * toolpath,
const MR_MeshPart * tool )

Compute bounding box for swept volume for given tool and toolpath Generated from function MR::computeWorkArea. Parameter toolpath can not be null. It is a single object. Parameter tool can not be null. It is a single object.

◆ MR_IComputeToolDistance_computeToolDistance()

MRC_API MR_expected_void_std_string * MR_IComputeToolDistance_computeToolDistance ( const MR_IComputeToolDistance * _this,
MR_std_vector_float * output,
const MR_Vector3i * dims,
float voxelSize,
const MR_Vector3f * origin,
float padding )

Compute tool distance Generated from a method of class MR::IComputeToolDistance named computeToolDistance. Parameter _this can not be null. It is a single object. Parameter output can not be null. It is a single object. Parameter dims can not be null. It is a single object. Parameter origin can not be null. It is a single object. Never returns null. Returns an instance allocated on the heap! Must call MR_expected_void_std_string_Destroy() to free it when you're done using it.

◆ MR_IComputeToolDistance_Destroy()

MRC_API void MR_IComputeToolDistance_Destroy ( const MR_IComputeToolDistance * _this)

Destroys a heap-allocated instance of MR_IComputeToolDistance. Does nothing if the pointer is null.

◆ MR_IComputeToolDistance_DestroyArray()

MRC_API void MR_IComputeToolDistance_DestroyArray ( const MR_IComputeToolDistance * _this)

Destroys a heap-allocated array of MR_IComputeToolDistance. Does nothing if the pointer is null.

◆ MR_IComputeToolDistance_OffsetMutablePtr()

MRC_API MR_IComputeToolDistance * MR_IComputeToolDistance_OffsetMutablePtr ( MR_IComputeToolDistance * ptr,
ptrdiff_t i )

Offsets a pointer to an array element by i positions (not bytes). Use only if you're certain that the pointer points to an array element.

◆ MR_IComputeToolDistance_OffsetPtr()

MRC_API const MR_IComputeToolDistance * MR_IComputeToolDistance_OffsetPtr ( const MR_IComputeToolDistance * ptr,
ptrdiff_t i )

Offsets a pointer to an array element by i positions (not bytes). Use only if you're certain that the pointer points to an array element.

◆ MR_IComputeToolDistance_prepare_MR_EndMillTool()

MRC_API MR_expected_MR_Vector3i_std_string * MR_IComputeToolDistance_prepare_MR_EndMillTool ( MR_IComputeToolDistance * _this,
const MR_Vector3i * dims,
const MR_Polyline3 * toolpath,
const MR_EndMillTool * toolSpec )

Prepare for a voxel grid of given dims and copy tool path and tool spec data

Returns
Maximum dimensions that can be processed at once (e.g. due to memory limits) Generated from a method of class MR::IComputeToolDistance named prepare. Parameter _this can not be null. It is a single object. Parameter dims can not be null. It is a single object. Parameter toolpath can not be null. It is a single object. Parameter toolSpec can not be null. It is a single object. Never returns null. Returns an instance allocated on the heap! Must call MR_expected_MR_Vector3i_std_string_Destroy() to free it when you're done using it.

◆ MR_IComputeToolDistance_prepare_MR_Polyline2()

MRC_API MR_expected_MR_Vector3i_std_string * MR_IComputeToolDistance_prepare_MR_Polyline2 ( MR_IComputeToolDistance * _this,
const MR_Vector3i * dims,
const MR_Polyline3 * toolpath,
const MR_Polyline2 * toolProfile )

Prepare for a voxel grid of given dims and copy tool path and tool spec data

Returns
Maximum dimensions that can be processed at once (e.g. due to memory limits) Generated from a method of class MR::IComputeToolDistance named prepare. Parameter _this can not be null. It is a single object. Parameter dims can not be null. It is a single object. Parameter toolpath can not be null. It is a single object. Parameter toolProfile can not be null. It is a single object. Never returns null. Returns an instance allocated on the heap! Must call MR_expected_MR_Vector3i_std_string_Destroy() to free it when you're done using it.