Houdini Engine 3.5
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Materials

Functions

HAPI_DECL HAPI_GetMaterialNodeIdsOnFaces (const HAPI_Session *session, HAPI_NodeId geometry_node_id, HAPI_PartId part_id, HAPI_Bool *are_all_the_same, HAPI_NodeId *material_ids_array, int start, int length)
 Get material ids by face/primitive. The material ids returned will be valid as long as the asset is alive. You should query this list after every cook to see if the material assignments have changed. You should also query each material individually using HAPI_GetMaterialInfo() to see if it is dirty and needs to be re-imported. More...
 
HAPI_DECL HAPI_GetMaterialInfo (const HAPI_Session *session, HAPI_NodeId material_node_id, HAPI_MaterialInfo *material_info)
 Get the material info. More...
 
HAPI_DECL HAPI_RenderCOPToImage (const HAPI_Session *session, HAPI_NodeId cop_node_id)
 Render a single texture from a COP to an image for later extraction. More...
 
HAPI_DECL HAPI_RenderTextureToImage (const HAPI_Session *session, HAPI_NodeId material_node_id, HAPI_ParmId parm_id)
 Render only a single texture to an image for later extraction. An example use of this method might be to render the diffuse, normal, and bump texture maps of a material to individual texture files for use within the client application. More...
 
HAPI_DECL HAPI_GetImageInfo (const HAPI_Session *session, HAPI_NodeId material_node_id, HAPI_ImageInfo *image_info)
 Get information about the image that was just rendered, like resolution and default file format. This information will be used when extracting planes to an image. More...
 
HAPI_DECL HAPI_SetImageInfo (const HAPI_Session *session, HAPI_NodeId material_node_id, const HAPI_ImageInfo *image_info)
 Set image information like resolution and file format. This information will be used when extracting planes to an image. More...
 
HAPI_DECL HAPI_GetImagePlaneCount (const HAPI_Session *session, HAPI_NodeId material_node_id, int *image_plane_count)
 Get the number of image planes for the just rendered image. More...
 
HAPI_DECL HAPI_GetImagePlanes (const HAPI_Session *session, HAPI_NodeId material_node_id, HAPI_StringHandle *image_planes_array, int image_plane_count)
 Get the names of the image planes of the just rendered image. More...
 
HAPI_DECL HAPI_ExtractImageToFile (const HAPI_Session *session, HAPI_NodeId material_node_id, const char *image_file_format_name, const char *image_planes, const char *destination_folder_path, const char *destination_file_name, int *destination_file_path)
 Extract a rendered image to a file. More...
 
HAPI_DECL HAPI_GetImageFilePath (const HAPI_Session *session, HAPI_NodeId material_node_id, const char *image_file_format_name, const char *image_planes, const char *destination_folder_path, const char *destination_file_name, HAPI_ParmId texture_parm_id, int *destination_file_path)
 Get the file name that this image would be saved to. More...
 
HAPI_DECL HAPI_ExtractImageToMemory (const HAPI_Session *session, HAPI_NodeId material_node_id, const char *image_file_format_name, const char *image_planes, int *buffer_size)
 Extract a rendered image to memory. More...
 
HAPI_DECL HAPI_GetImageMemoryBuffer (const HAPI_Session *session, HAPI_NodeId material_node_id, char *buffer, int length)
 Fill your allocated buffer with the just extracted image buffer. More...
 
HAPI_DECL HAPI_GetSupportedImageFileFormatCount (const HAPI_Session *session, int *file_format_count)
 Get the number of supported texture file formats. More...
 
HAPI_DECL HAPI_GetSupportedImageFileFormats (const HAPI_Session *session, HAPI_ImageFileFormat *formats_array, int file_format_count)
 Get a list of support image file formats - their names, descriptions and a list of recognized extensions. More...
 

Detailed Description

Functions for working with materials

Function Documentation

HAPI_DECL HAPI_ExtractImageToFile ( const HAPI_Session session,
HAPI_NodeId  material_node_id,
const char *  image_file_format_name,
const char *  image_planes,
const char *  destination_folder_path,
const char *  destination_file_name,
int *  destination_file_path 
)

Extract a rendered image to a file.

Note that you must call HAPI_RenderTextureToImage() first for this method call to make sense.

Parameters
[in]sessionThe session of Houdini you are interacting with. See Sessions for more on sessions. Pass NULL to just use the default in-process session.
[in]material_node_idThe material node id.
[in]image_file_format_nameThe image file format name you wish the image to be extracted as. You can leave this parameter NULL to get the image in the original format if it comes from another texture file or in the default HAPI format, which is HAPI_DEFAULT_IMAGE_FORMAT_NAME, if the image is generated.

You can get some of the very common standard image file format names from HAPI_Common.h under the "Defines" section.

You can also get a list of all supported file formats (and the exact names this parameter expects) by using HAPI_GetSupportedImageFileFormats(). This list will include custom file formats you created via custom DSOs (see HDK docs about IMG_Format). You will get back a list of HAPI_ImageFileFormat. This parameter expects the HAPI_ImageFileFormat::nameSH of a given image file format.

Parameters
[in]image_planesThe image planes you wish to extract into the file. Multiple image planes should be separated by spaces.
[in]destination_folder_pathThe folder where the image file should be created.
[in]destination_file_nameOptional parameter to overwrite the name of the extracted texture file. This should NOT include the extension as the file type will be decided by the HAPI_ImageInfo you can set using HAPI_SetImageInfo(). You still have to use destination_file_path to get the final file path.

Pass in NULL to have the file name be automatically generated from the name of the material SHOP node, the name of the texture map parameter if the image was rendered from a texture, and the image plane names specified.

Parameters
[out]destination_file_pathThe full path string handle, including the destination_folder_path and the texture file name, to the extracted file. Note that this string handle will only be valid until the next call to this function.
HAPI_DECL HAPI_ExtractImageToMemory ( const HAPI_Session session,
HAPI_NodeId  material_node_id,
const char *  image_file_format_name,
const char *  image_planes,
int *  buffer_size 
)

Extract a rendered image to memory.

Note that you must call HAPI_RenderTextureToImage() first for this method call to make sense.

Also note that this function will do all the work of extracting and compositing the image into a memory buffer but will not return to you that buffer, only its size. Use the returned size to allocated a sufficiently large buffer and call HAPI_GetImageMemoryBuffer() to fill your buffer with the just extracted image.

Parameters
[in]sessionThe session of Houdini you are interacting with. See Sessions for more on sessions. Pass NULL to just use the default in-process session.
[in]material_node_idThe material node id.
[in]image_file_format_nameThe image file format name you wish the image to be extracted as. You can leave this parameter NULL to get the image in the original format if it comes from another texture file or in the default HAPI format, which is HAPI_DEFAULT_IMAGE_FORMAT_NAME, if the image is generated.

You can get some of the very common standard image file format names from HAPI_Common.h under the "Defines" section.

You can also get a list of all supported file formats (and the exact names this parameter expects) by using HAPI_GetSupportedImageFileFormats(). This list will include custom file formats you created via custom DSOs (see HDK docs about IMG_Format). You will get back a list of HAPI_ImageFileFormat. This parameter expects the HAPI_ImageFileFormat::nameSH of a given image file format.

Parameters
[in]image_planesThe image planes you wish to extract into the file. Multiple image planes should be separated by spaces.
[out]buffer_sizeThe extraction will be done to an internal buffer who's size you get via this parameter. Use the returned buffer_size when calling HAPI_GetImageMemoryBuffer() to get the image buffer you just extracted.
HAPI_DECL HAPI_GetImageFilePath ( const HAPI_Session session,
HAPI_NodeId  material_node_id,
const char *  image_file_format_name,
const char *  image_planes,
const char *  destination_folder_path,
const char *  destination_file_name,
HAPI_ParmId  texture_parm_id,
int *  destination_file_path 
)

Get the file name that this image would be saved to.

Check to see what file path HAPI_ExtractImageToFile would have saved to given the same parms. Perhaps you might wish to see if it already exists before extracting.

Parameters
[in]sessionThe session of Houdini you are interacting with. See Sessions for more on sessions. Pass NULL to just use the default in-process session.
[in]material_node_idThe material node id.
[in]image_file_format_nameThe image file format name you wish the image to be extracted as. See HAPI_ExtractImageToFile for more information.
[in]image_planesThe image planes you wish to extract into the file. Multiple image planes should be separated by spaces.
[in]destination_folder_pathThe folder where the image file sould be created.
[in]destination_file_nameOptional parameter to overwrite the name of the extracted texture file. See HAPI_ExtractImageToFile for more information.
[in]texture_parm_idThe index in the parameter list of the material node. of the parameter containing the texture map file path
[out]destination_file_pathThe full path string handle, including the destination_folder_path and the texture file name, to the extracted file. Note that this string handle will only be valid until the next call to this function.
HAPI_DECL HAPI_GetImageInfo ( const HAPI_Session session,
HAPI_NodeId  material_node_id,
HAPI_ImageInfo image_info 
)

Get information about the image that was just rendered, like resolution and default file format. This information will be used when extracting planes to an image.

Note that you must call HAPI_RenderTextureToImage() first for this method call to make sense.

Parameters
[in]sessionThe session of Houdini you are interacting with. See Sessions for more on sessions. Pass NULL to just use the default in-process session.
[in]material_node_idThe material node id.
[out]image_infoThe struct containing the image information.
HAPI_DECL HAPI_GetImageMemoryBuffer ( const HAPI_Session session,
HAPI_NodeId  material_node_id,
char *  buffer,
int  length 
)

Fill your allocated buffer with the just extracted image buffer.

Note that you must call HAPI_RenderTextureToImage() first for this method call to make sense.

Also note that you must call HAPI_ExtractImageToMemory() first in order to perform the extraction and get the extracted image buffer size that you need to know how much memory to allocated to fit your extracted image.

Parameters
[in]sessionThe session of Houdini you are interacting with. See Sessions for more on sessions. Pass NULL to just use the default in-process session.
[in]material_node_idThe material node id.
[out]bufferThe buffer passed in here will be filled with the image buffer created during the call to HAPI_ExtractImageToMemory().
[in]lengthSanity check. This size should be the same as the size allocated for the buffer passed in and should be at least as large as the buffer_size returned by the call to HAPI_ExtractImageToMemory().
HAPI_DECL HAPI_GetImagePlaneCount ( const HAPI_Session session,
HAPI_NodeId  material_node_id,
int *  image_plane_count 
)

Get the number of image planes for the just rendered image.

Note that you must call HAPI_RenderTextureToImage() first for this method call to make sense.

Parameters
[in]sessionThe session of Houdini you are interacting with. See Sessions for more on sessions. Pass NULL to just use the default in-process session.
[in]material_node_idThe material node id.
[out]image_plane_countThe number of image planes.
HAPI_DECL HAPI_GetImagePlanes ( const HAPI_Session session,
HAPI_NodeId  material_node_id,
HAPI_StringHandle image_planes_array,
int  image_plane_count 
)

Get the names of the image planes of the just rendered image.

Note that you must call HAPI_RenderTextureToImage() first for this method call to make sense.

You should also call HAPI_GetImagePlaneCount() first to get the total number of image planes so you know how large the image_planes string handle array should be.

Parameters
[in]sessionThe session of Houdini you are interacting with. See Sessions for more on sessions. Pass NULL to just use the default in-process session.
[in]material_node_idThe material node id.
[out]image_planes_arrayThe image plane names.
[in]image_plane_countThe number of image planes to get names for. This must be less than or equal to the count returned by HAPI_GetImagePlaneCount().
HAPI_DECL HAPI_GetMaterialInfo ( const HAPI_Session session,
HAPI_NodeId  material_node_id,
HAPI_MaterialInfo material_info 
)

Get the material info.

Parameters
[in]sessionThe session of Houdini you are interacting with. See Sessions for more on sessions. Pass NULL to just use the default in-process session.
[in]material_node_idThe material node id.
[out]material_infoThe returned material info.
HAPI_DECL HAPI_GetMaterialNodeIdsOnFaces ( const HAPI_Session session,
HAPI_NodeId  geometry_node_id,
HAPI_PartId  part_id,
HAPI_Bool are_all_the_same,
HAPI_NodeId material_ids_array,
int  start,
int  length 
)

Get material ids by face/primitive. The material ids returned will be valid as long as the asset is alive. You should query this list after every cook to see if the material assignments have changed. You should also query each material individually using HAPI_GetMaterialInfo() to see if it is dirty and needs to be re-imported.

Parameters
[in]sessionThe session of Houdini you are interacting with. See Sessions for more on sessions. Pass NULL to just use the default in-process session.
[in]geometry_node_idThe geometry node id.
[in]part_idThe part id.
[out]are_all_the_same(optional) If true, all faces on this part have the same material assignment. You can pass NULL here.
[out]material_ids_arrayAn array of HAPI_NodeId at least the size of length and at most the size of HAPI_PartInfo::faceCount.
[in]startThe starting index into the list of faces from which you wish to get the material ids from. Note that this should be less than HAPI_PartInfo::faceCount.
[in]lengthThe number of material ids you wish to get. Note that this should be at most: HAPI_PartInfo::faceCount - start.
HAPI_DECL HAPI_GetSupportedImageFileFormatCount ( const HAPI_Session session,
int *  file_format_count 
)

Get the number of supported texture file formats.

Parameters
[in]sessionThe session of Houdini you are interacting with. See Sessions for more on sessions. Pass NULL to just use the default in-process session.
[out]file_format_countThe number of supported texture file formats.
HAPI_DECL HAPI_GetSupportedImageFileFormats ( const HAPI_Session session,
HAPI_ImageFileFormat formats_array,
int  file_format_count 
)

Get a list of support image file formats - their names, descriptions and a list of recognized extensions.

Note that you MUST call HAPI_GetSupportedImageFileFormatCount() before calling this function for the first time.

Parameters
[in]sessionThe session of Houdini you are interacting with. See Sessions for more on sessions. Pass NULL to just use the default in-process session.
[out]formats_arrayThe list of HAPI_ImageFileFormat structs to be filled.
[in]file_format_countThe number of supported texture file formats. This should be at least as large as the count returned by HAPI_GetSupportedImageFileFormatCount().
HAPI_DECL HAPI_RenderCOPToImage ( const HAPI_Session session,
HAPI_NodeId  cop_node_id 
)

Render a single texture from a COP to an image for later extraction.

Note that you must call this first for any of the other material APIs to work.

Parameters
[in]sessionThe session of Houdini you are interacting with. See Sessions for more on sessions. Pass NULL to just use the default in-process session.
[in]cop_node_idThe COP node id.
HAPI_DECL HAPI_RenderTextureToImage ( const HAPI_Session session,
HAPI_NodeId  material_node_id,
HAPI_ParmId  parm_id 
)

Render only a single texture to an image for later extraction. An example use of this method might be to render the diffuse, normal, and bump texture maps of a material to individual texture files for use within the client application.

Note that you must call this first for any of the other material APIs to work.

Parameters
[in]sessionThe session of Houdini you are interacting with. See Sessions for more on sessions. Pass NULL to just use the default in-process session.
[in]material_node_idThe material node id.
[in]parm_idThis is the index in the parameter list of the material_id's node of the parameter containing the texture map file path.
HAPI_DECL HAPI_SetImageInfo ( const HAPI_Session session,
HAPI_NodeId  material_node_id,
const HAPI_ImageInfo image_info 
)

Set image information like resolution and file format. This information will be used when extracting planes to an image.

Note that you must call HAPI_RenderTextureToImage() first for this method call to make sense.

You should also first call HAPI_GetImageInfo() to get the current Image Info and change only the properties you don't like.

Parameters
[in]sessionThe session of Houdini you are interacting with. See Sessions for more on sessions. Pass NULL to just use the default in-process session.
[in]material_node_idThe material node id.
[in]image_infoThe struct containing the new image information.