hc_proto.h

Macro Definitions

HC_PROTO_DEFINED

Functions

void	`HC_Abort_Program`
void	`HC_Append_Modelling_Matrix`
void	`HC_DAppend_Modelling_Matrix`
void	`HC_Append_Texture_Matrix`
void	`HC_Begin_Alias_Search`
void	`HC_Begin_Callback_Name_Search`
void	`HC_Begin_Color_Name_Search`
void	`HC_Begin_Contents_Search`
void	`HC_Begin_Font_Search`
void	`HC_Begin_Glyph_Search`
void	`HC_Begin_Line_Style_Search`
void	`HC_Begin_Open_Segment_Search`
void	`HC_Begin_Segment_Search`
void	`HC_Begin_Shader_Search`
void	`HC_Begin_Shape_Search`
void	`HC_Begin_Texture_Search`
void	`HC_Begin_Local_Texture_Search`
void	`HC_Bring_To_Front`
void	`HC_Bring_To_Front_By_Key`
void	`HC_Close_Edge`
void	`HC_Close_Face`
void	`HC_Close_Geometry`
void	`HC_Close_LOD`
void	`HC_Close_Region`
void	`HC_Close_Segment`
void	`HC_Close_Vertex`
bool	`HC_Compile_Shader`
bool	`HC_Compute_Circumcuboid`
bool	`HC_Compute_Circumcuboid_By_Key`
bool	`HC_Compute_Circumsphere`
bool	`HC_Compute_Circumsphere_By_Key`
bool	`HC_DCompute_Circumcuboid`
bool	`HC_DCompute_Circumcuboid_By_Key`
bool	`HC_DCompute_Circumsphere`
bool	`HC_DCompute_Circumsphere_By_Key`
bool	`HC_Compute_Color`
bool	`HC_Compute_Color_By_Value`
void	`HC_Compute_Convex_Hull`
bool	`HC_Compute_Coordinates`
bool	`HC_Compute_Coordinates_By_Path`
void	`HC_Compute_Cross_Product`
void	`HC_DCompute_Cross_Product`
double	`HC_Compute_Dot_Product`
double	`HC_DCompute_Dot_Product`
void	`HC_Compute_Identity_Matrix`
void	`HC_DCompute_Identity_Matrix`
void	`HC_Compute_Matrix_Adjoint`
void	`HC_DCompute_Matrix_Adjoint`
double	`HC_Compute_Matrix_Determinant`
double	`HC_DCompute_Matrix_Determinant`
bool	`HC_Compute_Matrix_Inverse`
bool	`HC_DCompute_Matrix_Inverse`
void	`HC_Compute_Matrix_Product`
void	`HC_DCompute_Matrix_Product`
void	`HC_Compute_Minimized_Shell`
bool	`HC_Compute_Normalized_Matrix`
bool	`HC_DCompute_Normalized_Matrix`
bool	`HC_Compute_Normalized_Vector`
bool	`HC_DCompute_Normalized_Vector`
void	`HC_Compute_Offaxis_Rotation`
void	`HC_DCompute_Offaxis_Rotation`
void	`HC_Compute_Offcenter_Rotation`
void	`HC_DCompute_Offcenter_Rotation`
void	`HC_Compute_Optimized_Shell`
Key	`HC_Compute_Capping_Shell`
Key	`HC_Compute_Boolean_Shell`
bool	`HC_Compute_Polygon_Normal`
bool	`HC_DCompute_Polygon_Normal`
bool	`HC_Compute_Polygon_Plane`
bool	`HC_DCompute_Polygon_Plane`
void	`HC_Compute_Rotation_Matrix`
void	`HC_DCompute_Rotation_Matrix`
void	`HC_Compute_Scale_Matrix`
void	`HC_DCompute_Scale_Matrix`
int	`HC_Compute_Selection`
int	`HC_Compute_Selection_By_Area`
int	`HC_Compute_Selection_By_Polygon`
int	`HC_Compute_Selection_By_Polylin`
int	`HC_Compute_Selection_By_Volume`
void	`HC_Compute_Text16_From_Text`
bool	`HC_Compute_Text_Extent`
bool	`HC_Compute_Text_Extent_By_Key`
bool	`HC_Compute_Text_Extent_By_Path`
bool	`HC_Compute_Text_Extent_Enc_Path`
bool	`HC_Compute_Text_Extent_With_Enc`
bool	`HC_Compute_Text_Metrics`
bool	`HC_Compute_Text_Metrics_Size`
void	`HC_Compute_Text_From_Text16`
void	`HC_Compute_Text_Outline`
void	`HC_Compute_Text_Outline_By_Key`
void	`HC_Compute_Text_Outline_Size`
void	`HC_Compute_Text_Outline_Size_By`
void	`HC_Compute_Text_Outline_Size_Wi`
void	`HC_Compute_Text_Outline_With_En`
void	`HC_Compute_Text_Outline_By_Path`
void	`HC_Compute_Text_Outline_Size_Pa`
bool	`HC_Compute_Transform`
bool	`HC_DCompute_Transform`
bool	`HC_Compute_Transform_By_Path`
bool	`HC_DCompute_Transform_By_Path`
bool	`HC_Compute_Transformed_Plane`
bool	`HC_DCompute_Transformed_Plane`
bool	`HC_Compute_Transformed_Planes`
bool	`HC_DCompute_Transformed_Planes`
void	`HC_Compute_Transformed_Points`
void	`HC_Compute_Translation_Matrix`
void	`HC_DCompute_Translation_Matrix`
double	`HC_Compute_Vector_Length`
double	`HC_DCompute_Vector_Length`
void	`HC_Control_Update`
void	`HC_Control_Update_Area`
void	`HC_Control_Update_Area_By_Key`
void	`HC_Control_Update_By_Key`
bool	`HC_Convert_Precision`
void	`HC_Define_Alias`
void	`HC_Define_Callback_Name`
void	`HC_Define_Color_Name`
void	`HC_Define_Driver_Config`
void	`HC_Define_Error_Handler`
void	`HC_Define_Exit_Handler`
void	`HC_Define_Font`
void	`HC_Define_Font_By_Reference`
void	`HC_Define_Glyph`
void	`HC_Define_Image_Glyph`
void	`HC_Define_Line_Style`
void	`HC_Define_Shape`
void	`HC_Define_System_Options`
void	`HC_Define_Texture`
void	`HC_Define_Local_Texture`
Key	`HC_Define_Shader`
void	`HC_Delete_By_Key`
void	`HC_Delete_Segment`
void	`HC_Dolly_Camera`
intptr_t	`HC_Dump_Memory_Profile`
void	`HC_Edit_Image`
void	`HC_Edit_Image_Options`
void	`HC_Edit_Mesh`
void	`HC_Edit_NURBS_Curve`
void	`HC_Edit_Polygon`
void	`HC_Edit_Polyline`
void	`HC_Edit_Shell_Faces`
void	`HC_Edit_Shell_Points`
void	`HC_Edit_Text`
void	`HC_Edit_Text_Leader`
void	`HC_End_Alias_Search`
void	`HC_End_Callback_Name_Search`
void	`HC_End_Color_Name_Search`
void	`HC_End_Contents_Search`
void	`HC_End_Font_Search`
void	`HC_End_Open_Segment_Search`
void	`HC_End_Segment_Search`
void	`HC_End_Texture_Search`
void	`HC_End_Shader_Search`
void	`HC_End_Glyph_Search`
void	`HC_End_Line_Style_Search`
void	`HC_End_Shape_Search`
void	`HC_Exit_Program`
bool	`HC_Find_Alias`
bool	`HC_Find_Callback_Name`
bool	`HC_Find_Color_Name`
bool	`HC_Find_Contents`
bool	`HC_Find_Contents_Original_Key`
bool	`HC_Find_Font`
bool	`HC_Find_Open_Segment`
bool	`HC_Find_Related_Selection`
bool	`HC_Find_Segment`
bool	`HC_Find_Texture`
bool	`HC_Find_Shader`
bool	`HC_Find_Glyph`
bool	`HC_Find_Line_Style`
bool	`HC_Find_Shape`
void	`HC_Flush_Attributes`
void	`HC_Flush_By_Key`
void	`HC_Flush_Contents`
void	`HC_Flush_Geometry`
void	`HC_Edit_Sphere`
void	`HC_Edit_Circle`
void	`HC_Edit_Circle_By_Radius`
void	`HC_Edit_Circular_Arc`
void	`HC_Edit_Circular_Chord`
void	`HC_Edit_Circular_Wedge`
void	`HC_Edit_Cutting_Plane`
void	`HC_Edit_Ellipse`
void	`HC_Edit_Elliptical_Arc`
void	`HC_Edit_Grid`
void	`HC_Edit_Line`
void	`HC_Edit_Infinite_Line`
void	`HC_Edit_Infinite_Ray`
void	`HC_DEdit_Infinite_Line`
void	`HC_DEdit_Infinite_Ray`
void	`HC_Edit_Marker`
void	`HC_Edit_Cylinder`
void	`HC_Edit_PolyCylinder_Points`
void	`HC_Edit_PolyCylinder_Radii`
void	`HC_DEdit_PolyCylinder_Points`
void	`HC_DEdit_PolyCylinder_Radii`
void	`HC_Edit_PolyCylinder`
void	`HC_Edit_PolyCylinder_With_Basis`
Key	`HC_Copy_Geometry`
Key	`HC_Copy_Segment`
Key	`HC_Create_Segment`
Key	`HC_Include_Segment`
Key	`HC_Include_Segment_By_Key`
Key	`HC_Insert_Area_Light`
Key	`HC_Insert_Circle`
Key	`HC_Insert_Circular_Arc`
Key	`HC_Insert_Circular_Chord`
Key	`HC_Insert_Circular_Wedge`
Key	`HC_Insert_Cutting_Plane`
Key	`HC_Insert_Cylinder`
Key	`HC_Insert_Sphere`
Key	`HC_Insert_Circle_By_Radius`
Key	`HC_Insert_Distant_Light`
Key	`HC_Insert_Ellipse`
Key	`HC_Insert_Elliptical_Arc`
Key	`HC_Insert_Grid`
Key	`HC_Insert_Image`
Key	`HC_Insert_Compressed_Image`
Key	`HC_Insert_Image_By_Ref`
Key	`HC_DInsert_Image_By_Ref`
Key	`HC_Insert_Ink`
Key	`HC_Insert_Line`
Key	`HC_Insert_Infinite_Line`
Key	`HC_Insert_Infinite_Ray`
Key	`HC_DInsert_Infinite_Line`
Key	`HC_DInsert_Infinite_Ray`
Key	`HC_Insert_Local_Light`
Key	`HC_Insert_Marker`
Key	`HC_Insert_Mesh`
Key	`HC_Insert_Mesh_By_Ref`
Key	`HC_DInsert_Mesh_By_Ref`
Key	`HC_Insert_NURBS_Curve`
Key	`HC_Insert_Polygon`
Key	`HC_Insert_Polyline`
Key	`HC_Insert_Shell`
Key	`HC_Insert_Shell_By_Ref`
Key	`HC_DInsert_Shell_By_Ref`
Key	`HC_Insert_Shell_By_Tristrips`
Key	`HC_DInsert_Shell_By_Tristrips`
Key	`HC_Insert_Spot_Light`
Key	`HC_Insert_String_Cursor`
Key	`HC_Insert_Text`
Key	`HC_Insert_Text_Leader`
Key	`HC_Insert_Text_With_Encoding`
Key	`HC_Open_Segment`
Key	`HC_Renumber_Key`
Key	`HC_Show_Include_Segment`
Key	`HC_Show_Owner_Original_Key`
Key	`HC_Style_Segment`
Key	`HC_Style_Segment_By_Key`
void	`HC_MSet_Character_Attributes`
void	`HC_MUnSet_Character_Attributes`
void	`HC_MSet_Face_Normals`
void	`HC_MSet_Face_Colors_By_FIndex`
void	`HC_MSet_Face_Colors_By_Value`
void	`HC_MSet_Vertex_Colors_By_FIndex`
void	`HC_MSet_Vertex_Colors_By_Value`
void	`HC_MSet_Vertex_Colors_By_Value4`
void	`HC_MSet_Vertex_Normals`
void	`HC_MSet_Vertex_Parameters`
void	`HC_Modify_Color_Map`
void	`HC_Modify_Color_Map_By_Value`
void	`HC_Move_By_Key`
void	`HC_Move_Distant_Light`
void	`HC_Move_Image`
void	`HC_Move_Light_Position`
void	`HC_Move_Light_Target`
void	`HC_Move_Segment`
void	`HC_Move_String_Cursor`
void	`HC_Move_Text`
void	`HC_Open_Edge`
void	`HC_Open_Face`
void	`HC_Open_Geometry`
void	`HC_Open_LOD`
void	`HC_Open_Region`
void	`HC_Open_Segment_By_Key`
void	`HC_Open_Vertex`
void	`HC_Orbit_Camera`
bool	`HC_PShow_Net_Callback`
int	`HC_PShow_Net_Camera`
int	`HC_PShow_Net_Camera_By_Volume`
int	`HC_PShow_Net_Camera_Position`
int	`HC_PShow_Net_Camera_Target`
int	`HC_PShow_Net_Camera_Up_Vector`
int	`HC_PShow_Net_Camera_Field`
int	`HC_PShow_Net_Camera_Projection`
int	`HC_DPShow_Net_Camera`
int	`HC_DPShow_Net_Camera_By_Volume`
int	`HC_DPShow_Net_Camera_Position`
int	`HC_DPShow_Net_Camera_Target`
int	`HC_DPShow_Net_Camera_Up_Vector`
int	`HC_DPShow_Net_Camera_Field`
bool	`HC_PShow_Net_Color`
bool	`HC_PShow_Net_Color_Map`
bool	`HC_PShow_Net_Color_Map_By_Value`
bool	`HC_PShow_Net_Color_Map_Count`
bool	`HC_PShow_Net_Driver_Options`
bool	`HC_PShow_Net_Edge_Pattern`
bool	`HC_PShow_Net_Edge_Weight`
bool	`HC_PShow_Net_Face_Pattern`
bool	`HC_PShow_Net_Handedness`
bool	`HC_PShow_Net_Heuristics`
bool	`HC_PShow_Net_Line_Pattern`
bool	`HC_PShow_Net_Line_Weight`
bool	`HC_PShow_Net_Marker_Size`
bool	`HC_PShow_Net_Marker_Symbol`
int	`HC_PShow_Net_Modelling_Matrix`
int	`HC_DPShow_Net_Modelling_Matrix`
bool	`HC_PShow_Net_Rendering_Options`
bool	`HC_PShow_Net_Selectability`
bool	`HC_PShow_Net_Text_Alignment`
bool	`HC_PShow_Net_Text_Font`
bool	`HC_PShow_Net_Text_Path`
bool	`HC_PShow_Net_Text_Spacing`
bool	`HC_PShow_Net_Texture_Matrix`
bool	`HC_PShow_Net_User_Index_Count`
bool	`HC_PShow_Net_User_Indices`
bool	`HC_PShow_Net_User_Options`
bool	`HC_PShow_Net_Unicode_Options`
bool	`HC_PShow_Net_User_Opt_Length`
bool	`HC_PShow_Net_Unicode_Opt_Length`
bool	`HC_PShow_Net_User_Value`
bool	`HC_PShow_Net_Visibility`
bool	`HC_PShow_Net_Window`
bool	`HC_PShow_Net_Window_With_Options`
bool	`HC_PShow_Net_Window_Frame`
bool	`HC_PShow_Net_Window_Pattern`
bool	`HC_PShow_One_Net_Callback`
bool	`HC_PShow_One_Net_Callback_WD`
bool	`HC_PShow_One_Net_Color`
bool	`HC_PShow_One_Net_Color_By_Index`
bool	`HC_PShow_One_Net_Color_By_Value`
bool	`HC_PShow_One_Net_Color_Map`
bool	`HC_PShow_One_Net_Color_Map_By_V`
bool	`HC_PShow_One_Net_Driver_Option`
bool	`HC_PShow_One_Net_Heuristic`
bool	`HC_PShow_One_Net_Rendering_Opti`
bool	`HC_PShow_One_Net_Selectability`
bool	`HC_PShow_One_Net_Text_Font`
bool	`HC_PShow_One_Net_User_Index`
bool	`HC_PShow_One_Net_User_Option`
bool	`HC_PShow_One_Net_Unicode_Opt`
bool	`HC_PShow_One_Net_Visibility`
void	`HC_Pan_Camera`
bool	`HC_Parse_String`
void	`HC_Pause`
void	`HC_Print_Version`
int	`HC_QShow_Existence`
int	`HC_Show_Existence`
int	`HC_Show_Existence_By_Key`
int	`HC_QShow_Existence_Unicode`
int	`HC_Show_Existence_Unicode`
int	`HC_Show_Existence_Unicode_By_K`
bool	`HC_Read_Metafile`
void	`HC_Record_Instance_Handle`
void	`HC_Record_Profile_Source`
void	`HC_Relinquish_Memory`
void	`HC_Rename_Segment`
void	`HC_Rename_Segment_By_Key`
void	`HC_Report_Error`
void	`HC_Reset_System`
void	`HC_Restart_Ink`
void	`HC_Roll_Camera`
void	`HC_Rotate_Object`
void	`HC_Rotate_Object_Offaxis`
void	`HC_DRotate_Object`
void	`HC_DRotate_Object_Offaxis`
void	`HC_Rotate_Texture`
void	`HC_Rotate_Texture_Offaxis`
void	`HC_Scale_Object`
void	`HC_DScale_Object`
void	`HC_Scale_Texture`
void	`HC_Scroll_Text`
void	`HC_Set_Bounding_Cuboid`
void	`HC_Set_Bounding_Sphere`
void	`HC_DSet_Bounding_Cuboid`
void	`HC_DSet_Bounding_Sphere`
void	`HC_Set_Callback`
void	`HC_Set_Callback_With_Data`
void	`HC_Set_Camera`
void	`HC_Set_Camera_By_Volume`
void	`HC_Set_Camera_Field`
void	`HC_Set_Camera_Position`
void	`HC_Set_Camera_Projection`
void	`HC_Set_Camera_Target`
void	`HC_Set_Camera_Up_Vector`
void	`HC_Set_Color`
void	`HC_Set_Explicit_Color`
void	`HC_Set_Color_By_FIndex`
void	`HC_Set_Color_By_Index`
void	`HC_Set_Color_By_Value`
void	`HC_Set_Color_Map`
void	`HC_Set_Color_Map_By_Value`
void	`HC_Set_Driver_Options`
void	`HC_Set_Edge_Pattern`
void	`HC_Set_Edge_Pattern_Explicit`
void	`HC_Set_Edge_Weight`
void	`HC_Set_Face_Pattern`
void	`HC_Set_Handedness`
void	`HC_Set_Heuristics`
void	`HC_Set_Line_Pattern`
void	`HC_Set_Line_Pattern_Explicit`
void	`HC_Set_Line_Weight`
void	`HC_Set_Marker_Size`
void	`HC_Set_Marker_Symbol`
void	`HC_Set_Modelling_Matrix`
void	`HC_DSet_Modelling_Matrix`
void	`HC_Set_Normal`
void	`HC_Set_Parameter`
void	`HC_Set_Priority`
void	`HC_UnSet_PBR_Material`
void	`HC_Set_PBR_Material`
bool	`HC_Show_PBR_Material`
bool	`HC_PShow_Net_PBR_Material`
void	`HC_Set_Rendering_Options`
void	`HC_Set_Selectability`
void	`HC_Set_Shader`
void	`HC_Set_Shader_Outputs`
bool	`HC_Show_Shader_Outputs_Size`
bool	`HC_Show_Shader_Outputs`
void	`HC_UnSet_Shader_Outputs`
void	`HC_Set_Shader_Uniforms`
bool	`HC_Set_Shader_Uniforms_Data`
bool	`HC_Show_Shader_Uniforms_Data_Size`
bool	`HC_Show_Shader_Uniforms_Data`
bool	`HC_Show_Shader_Uniforms_Size`
bool	`HC_Show_Shader_Uniforms`
void	`HC_UnSet_Shader_Uniforms`
void	`HC_Set_Streaming_Mode`
void	`HC_Set_Text_Alignment`
void	`HC_Set_Text_Font`
void	`HC_Set_Text_Path`
void	`HC_Set_Text_Size`
void	`HC_Set_Text_Spacing`
void	`HC_Set_Texture_Matrix`
void	`HC_Set_User_Index`
void	`HC_Set_User_Options`
void	`HC_Set_Unicode_Options`
void	`HC_Set_User_Value`
void	`HC_Set_Visibility`
void	`HC_Set_Window`
void	`HC_Set_Window_With_Options`
void	`HC_Set_Window_Frame`
void	`HC_Set_Window_Pattern`
void	`HC_Show_Alias`
void	`HC_Show_Alias_Count`
void	`HC_Show_Area_Light`
void	`HC_Show_Area_Light_Count`
bool	`HC_Show_Bounding_Cuboid`
bool	`HC_Show_Bounding_Cuboid_By_Key`
bool	`HC_DShow_Bounding_Cuboid`
bool	`HC_DShow_Bounding_Cuboid_By_Key`
void	`HC_Show_Bounding_Info`
void	`HC_Show_Bounding_Info_By_Key`
bool	`HC_Show_Bounding_Sphere`
bool	`HC_Show_Bounding_Sphere_By_Key`
bool	`HC_DShow_Bounding_Sphere`
bool	`HC_DShow_Bounding_Sphere_By_Key`
void	`HC_Show_Button`
void	`HC_Show_Button_Source`
void	`HC_Show_Callback`
void	`HC_Show_Callback_Name`
void	`HC_Show_Callback_Name_Count`
void	`HC_Show_Camera`
void	`HC_Show_Camera_By_Volume`
void	`HC_Show_Camera_Field`
void	`HC_Show_Camera_Position`
void	`HC_Show_Camera_Projection`
void	`HC_Show_Camera_Target`
void	`HC_Show_Camera_Up_Vector`
void	`HC_Show_Circle`
void	`HC_Show_Circular_Arc`
void	`HC_Show_Circular_Chord`
void	`HC_Show_Circular_Wedge`
void	`HC_Show_Color`
void	`HC_Show_Color_By_Index`
void	`HC_Show_Color_By_Value`
void	`HC_Show_Color_Map`
void	`HC_Show_Color_Map_By_Value`
void	`HC_Show_Color_Map_Count`
void	`HC_Show_Color_Name`
void	`HC_Show_Color_Name_Count`
void	`HC_Show_Compilation_Results`
void	`HC_Show_Compilation_Results_Size`
void	`HC_Show_Explicit_Color`
bool	`HC_PShow_Net_Explicit_Color`
void	`HC_Show_Contents_Count`
void	`HC_Show_Cutting_Plane`
void	`HC_Show_Cylinder`
void	`HC_Show_Circle_By_Radius`
void	`HC_Show_Sphere`
void	`HC_Show_Device_Info`
void	`HC_Show_Device_Info_By_Key`
void	`HC_Show_Distant_Light`
void	`HC_Show_Driver_Options`
void	`HC_Show_Edge_Pattern`
void	`HC_Show_Edge_Pattern_Explicit`
void	`HC_Show_Edge_Weight`
void	`HC_Show_Ellipse`
void	`HC_Show_Elliptical_Arc`
bool	`HC_Show_Environment`
void	`HC_Show_Face_Pattern`
void	`HC_Show_Font`
void	`HC_Show_Font_Count`
void	`HC_Show_Font_Info`
void	`HC_Show_Font_Size`
void	`HC_Show_Grid`
void	`HC_Show_Handedness`
void	`HC_Show_Heuristics`
void	`HC_Show_Image`
void	`HC_Show_Image_Size`
bool	`HC_Show_Snapshot`
void	`HC_Show_Compressed_Image`
void	`HC_Show_Compressed_Image_Size`
int	`HC_Show_Image_Bytes_Per_Pixel`
void	`HC_Show_Image_Format`
void	`HC_Show_Image_Name`
void	`HC_Show_Glyph`
void	`HC_Show_Glyph_Size`
bool	`HC_Show_Shader`
void	`HC_Show_Shape`
void	`HC_Show_Shape_Size`
void	`HC_Show_Line_Style`
void	`HC_Show_Line_Style_Size`
void	`HC_Show_Line_Pattern`
void	`HC_Show_Line_Pattern_Explicit`
void	`HC_Show_Key_Status`
void	`HC_Show_Key_Type`
void	`HC_Show_LOD_Type`
void	`HC_Show_Line`
void	`HC_Show_Infinite_Line`
void	`HC_Show_Infinite_Ray`
void	`HC_DShow_Infinite_Line`
void	`HC_DShow_Infinite_Ray`
void	`HC_Show_Line_Weight`
void	`HC_Show_Local_Light`
void	`HC_Show_Location`
void	`HC_Show_Location_Source`
void	`HC_Show_Marker`
void	`HC_Show_Marker_Size`
void	`HC_Show_Marker_Symbol`
void	`HC_Show_Memory_Usage`
void	`HC_Show_Memory_Statistics`
void	`HC_Show_Mesh`
void	`HC_Show_Mesh_Size`
void	`HC_Show_Modelling_Matrix`
void	`HC_DShow_Modelling_Matrix`
void	`HC_Show_NURBS_Curve`
void	`HC_Show_NURBS_Curve_Size`
void	`HC_Show_Normal`
void	`HC_Show_One_Callback`
void	`HC_Show_One_Callback_With_Data`
void	`HC_Show_One_Color`
void	`HC_Show_One_Color_By_Index`
bool	`HC_Show_One_Color_By_Value`
void	`HC_Show_One_Color_Map`
void	`HC_Show_One_Color_Map_By_Value`
void	`HC_Show_One_Driver_Option`
void	`HC_Show_One_Heuristic`
void	`HC_Show_One_Rendering_Option`
void	`HC_Show_One_Selectability`
void	`HC_Show_One_System_Option`
void	`HC_Show_One_Text_Font`
bool	`HC_Show_One_User_Index`
void	`HC_Show_One_User_Option`
void	`HC_Show_One_Unicode_Option`
void	`HC_Show_One_Visibility`
void	`HC_Show_Open_Segment_Count`
Key	`HC_Show_Owner`
Key	`HC_Show_Owner_By_Key`
void	`HC_Show_Parameter`
void	`HC_Show_Parameter_Size`
void	`HC_Show_Partial_Image`
void	`HC_Show_Partial_Mesh`
void	`HC_Show_Partial_Polygon`
void	`HC_Show_Partial_Polyline`
void	`HC_Show_Partial_Shell`
void	`HC_Show_Partial_Shell_Size`
void	`HC_DShow_Partial_Mesh`
void	`HC_DShow_Partial_Polygon`
void	`HC_DShow_Partial_Polyline`
void	`HC_DShow_Partial_Shell`
void	`HC_Show_Pathname_Expansion`
void	`HC_Show_Polygon`
void	`HC_Show_Polygon_Count`
void	`HC_Show_Polyline`
void	`HC_Show_Polyline_Count`
bool	`HC_Show_Priority`
void	`HC_Show_Rendering_Options`
int	`HC_Show_Segment_Name_Length`
Key	`HC_Show_Segment_Name`
Key	`HC_Show_Segment`
void	`HC_Show_Segment_Count`
void	`HC_Show_Selectability`
void	`HC_Show_Selection`
void	`HC_Show_Selection_Element`
void	`HC_Show_Selection_Source_Elem`
void	`HC_DShow_Selection_Source_Elem`
void	`HC_Show_Selection_Original_Key`
void	`HC_Show_Selection_Elements`
void	`HC_Show_Selection_Elements_Coun`
void	`HC_Show_Selection_Item`
void	`HC_Show_Selection_Keys`
void	`HC_Show_Selection_Original_Keys`
void	`HC_Show_Selection_Keys_Count`
void	`HC_Show_Selection_Location`
void	`HC_Show_Selection_Pathname`
int	`HC_Show_Selection_Position`
int	`HC_DShow_Selection_Position`
void	`HC_Show_Selection_Source`
void	`HC_Show_Shell`
void	`HC_Show_Shell_By_Tristrips`
void	`HC_Show_Shell_By_Tristrips_Size`
void	`HC_Show_Shell_Size`
void	`HC_Show_Shell_Face_Count`
void	`HC_Show_Shell_Tristrip_Count`
void	`HC_Show_Spot_Light`
void	`HC_Show_Streaming_Mode`
void	`HC_Show_String`
void	`HC_Show_String_Count`
void	`HC_Show_String_Cursor`
void	`HC_Show_String_Length`
void	`HC_Show_String_Source`
void	`HC_Show_String_With_Encoding`
Key	`HC_Show_Style_Segment`
bool	`HC_Show_System_Info`
void	`HC_Show_System_Options`
void	`HC_Show_Text`
void	`HC_Show_Text_Leader`
void	`HC_Show_Text_With_Encoding`
void	`HC_Show_Text_Alignment`
void	`HC_Show_Text_Count`
void	`HC_Show_Text_Encoding`
void	`HC_Show_Text_Font`
void	`HC_Show_Text_Length`
void	`HC_Show_Text_Path`
void	`HC_Show_Text_Size`
void	`HC_Show_Text_Spacing`
void	`HC_Show_Texture`
void	`HC_Show_Shader_Definition`
void	`HC_Show_Shader_Definition_Source_Size`
void	`HC_Show_Shader_Definition_By_Key`
void	`HC_Set_Shader_Inputs`
bool	`HC_Show_Shader_Inputs_Size`
bool	`HC_Show_Shader_Inputs`
void	`HC_UnSet_Shader_Inputs`
Key	`HC_Define_Shader_Sampler`
bool	`HC_Show_Shader_Sampler_Def_Size`
bool	`HC_Show_Shader_Sampler_Def`
Key	`HC_Define_Shader_Texture`
bool	`HC_Show_Shader_Texture_Def_Size`
bool	`HC_Show_Shader_Texture_Def`
void	`HC_Set_Shader_Textures`
void	`HC_UnSet_Shader_Textures`
bool	`HC_Show_Shader_Textures_Count`
bool	`HC_Show_Shader_Textures`
void	`HC_Show_Local_Texture`
void	`HC_Show_Texture_Count`
void	`HC_Show_Glyph_Count`
void	`HC_Show_Shape_Count`
void	`HC_Show_Line_Style_Count`
void	`HC_Show_Texture_Matrix`
void	`HC_Show_Time`
void	`HC_Show_User_Index_Count`
void	`HC_Show_User_Indices`
void	`HC_Show_User_Options`
void	`HC_Show_Unicode_Options`
void	`HC_Show_User_Options_Length`
void	`HC_Show_Unicode_Options_Length`
void	`HC_Show_User_Value`
void	`HC_Show_Visibility`
void	`HC_Show_Wakeup`
void	`HC_Show_Window`
void	`HC_Show_Window_With_Options`
void	`HC_Show_Window_Frame`
void	`HC_Show_Window_Pattern`
void	`HC_Translate_Object`
void	`HC_DTranslate_Object`
void	`HC_Translate_Texture`
void	`HC_UnDefine_Alias`
void	`HC_UnDefine_Callback_Name`
void	`HC_UnDefine_Color_Name`
void	`HC_UnDefine_Error_Handler`
void	`HC_UnDefine_Exit_Handler`
void	`HC_UnDefine_Font`
void	`HC_UnDefine_Glyph`
void	`HC_UnDefine_Line_Style`
void	`HC_UnDefine_Shape`
void	`HC_UnDefine_Texture`
void	`HC_UnDefine_Local_Texture`
void	`HC_UnDefine_Shader`
void	`HC_UnSet_Bounding_Volume`
void	`HC_UnSet_Callback`
void	`HC_UnSet_Camera`
void	`HC_UnSet_Color`
void	`HC_UnSet_Color_Map`
void	`HC_UnSet_Driver_Options`
void	`HC_UnSet_Edge_Pattern`
void	`HC_UnSet_Edge_Weight`
void	`HC_UnSet_Face_Pattern`
void	`HC_UnSet_Handedness`
void	`HC_UnSet_Heuristics`
void	`HC_UnSet_Line_Pattern`
void	`HC_UnSet_Line_Weight`
void	`HC_UnSet_Marker_Size`
void	`HC_UnSet_Marker_Symbol`
void	`HC_UnSet_Modelling_Matrix`
void	`HC_UnSet_Normal`
void	`HC_UnSet_One_Callback`
void	`HC_UnSet_One_Color`
void	`HC_UnSet_One_Driver_Option`
void	`HC_UnSet_One_Heuristic`
void	`HC_UnSet_One_Rendering_Option`
void	`HC_UnSet_One_Selectability`
void	`HC_UnSet_One_Text_Font`
void	`HC_UnSet_One_User_Index`
void	`HC_UnSet_One_User_Option`
void	`HC_UnSet_One_Unicode_Option`
void	`HC_UnSet_One_Visibility`
void	`HC_UnSet_Parameter`
void	`HC_UnSet_Rendering_Options`
void	`HC_UnSet_Selectability`
void	`HC_UnSet_Shader`
void	`HC_UnSet_Streaming_Mode`
void	`HC_UnSet_Text_Alignment`
void	`HC_UnSet_Text_Font`
void	`HC_UnSet_Text_Path`
void	`HC_UnSet_Text_Spacing`
void	`HC_UnSet_Texture_Matrix`
void	`HC_UnSet_User_Options`
void	`HC_UnSet_Unicode_Options`
void	`HC_UnSet_User_Indices`
void	`HC_UnSet_User_Data`
void	`HC_UnSet_User_Value`
void	`HC_UnSet_Visibility`
void	`HC_UnSet_Window`
void	`HC_UnSet_Window_Frame`
void	`HC_UnSet_Window_Pattern`
bool	`HC_Update_Display`
bool	`HC_Update_Display_Timed`
bool	`HC_Update_One_Display`
bool	`HC_Update_One_Display_Timed`
bool	`HC_Write_Metafile`
void	`HC_Zoom_Camera`
void	`HC_Show_Geometry_Pointer`
void	`HC_Show_Geometry_Options`
void	`HC_Set_Geometry_Options`
Key	`HC_Insert_NURBS_Surface`
void	`HC_Show_NURBS_Surface_Size`
void	`HC_Show_NURBS_Surface`
void	`HC_Trim_NURBS_Surface_By_Poly`
void	`HC_Trim_NURBS_Surface_By_Curve`
void	`HC_Edit_NURBS_Surface`
void	`HC_Edit_NURBS_Surface_Points`
void	`HC_Edit_NURBS_Surface_Weights`
void	`HC_Edit_NURBS_Surface_Knots`
void	`HC_Show_Trim_Count`
void	`HC_Show_Trim_Type`
void	`HC_Show_Trim_Poly`
void	`HC_Show_Trim_Poly_Count`
void	`HC_Show_Trim_Curve`
void	`HC_Show_Trim_Curve_Count`
void	`HC_Delete_Trim`
void	`HC_Open_Trim`
void	`HC_Close_Trim`
void	`HC_Set_Trim_Operation`
void	`HC_Show_Trim_Operation`
void	`HC_Create_Trim_Collection`
void	`HC_Set_Variable_Line_Weight`
void	`HC_Set_Variable_Edge_Weight`
void	`HC_Set_Variable_Marker_Size`
void	`HC_Show_Variable_Edge_Weight`
void	`HC_Show_Variable_Line_Weight`
void	`HC_Show_Variable_Marker_Size`
bool	`HC_PShow_Net_Var_Edge_Weight`
bool	`HC_PShow_Net_Var_Line_Weight`
bool	`HC_PShow_Net_Var_Marker_Size`
void	`HC_MShow_Character_Attributes`
void	`HC_Show_Character_Attribute_Cou`
void	`HC_Show_One_Character_Attribute`
void	`HC_Set_Faces`
void	`HC_Set_Region`
void	`HC_MSet_Region_Faces`
void	`HC_MSet_Face_Regions`
void	`HC_Show_Faces`
void	`HC_Show_Faces_Count`
void	`HC_Show_Region`
void	`HC_MShow_Region_Faces`
void	`HC_MShow_Region_Faces_Count`
void	`HC_MShow_Face_Regions`
void	`HC_MShow_Face_Regions_Count`
void	`HC_MShow_Partial_Face_Regions`
void	`HC_Show_Region_Range`
Key	`HC_Insert_PolyCylinder`
void	`HC_Show_PolyCylinder`
void	`HC_Show_PolyCylinder_Counts`
Key	`HC_Insert_Shell_From_Region`
Key	`HC_Insert_Unicode_Text`
void	`HC_Show_Unicode_Text`
int	`HC_Compute_Selection_By_Shell`
int	`HC_DCompute_Selection_By_Shell`
int	`HC_Compute_Selection_By_Sh_W_Op`
int	`HC_DCompute_Selection_By_Sh_W_O`
int	`HC_Compute_Selection_By_Swept_S`
int	`HC_DCompute_Selection_By_Swpt_S`
int	`HC_Compute_Selection_By_Swept_2`
int	`HC_DCompute_Selection_By_Swpt_2`
int	`HC_Compute_Selection_By_Key`
int	`HC_DCompute_Selection_By_Key`
Key	`HC_Compute_Swept_Shell`
Key	`HC_DCompute_Swept_Shell`
void	`HC_Compute_Swept_Shell_Along_P`
void	`HC_DCompute_Swept_Shell_Along_P`
float	`HC_Compute_Selection_Dist_By_Sh`
double	`HC_DCompute_Selection_Dist_By_S`
void	`HC_Begin_Shell_Selection`
void	`HC_End_Shell_Selection`
int	`HC_Compute_Intersect_Polyline`
int	`HC_Show_Intersect_Polyline_Size`
int	`HC_DCompute_Intersect_Polyline`
int	`HC_DShow_Intersect_Polyline_Size`
bool	`HC_Compute_Point_Inside_Shell`
bool	`HC_DCompute_Point_Inside_Shell`
bool	`HC_Compute_Point_On_Shell`
bool	`HC_DCompute_Point_On_Shell`
void	`HC_Compute_Points_Inside_Shell`
void	`HC_DCompute_Points_Inside_Shell`
int	`HC_Compute_Points_On_Shell`
int	`HC_DCompute_Points_On_Shell`
int	`HC_Compute_Points_Distance_F_Sh`
int	`HC_DCompute_Points_Distance_F_S`
int	`HC_Compute_Points_Distance_F_S2`
int	`HC_DCompute_Points_Distance_FS2`
void	`HC_Compute_Shell_Enclosure`
void	`HC_DCompute_Shell_Enclosure`
int	`HC_Compute_Selection_By_Ray`
int	`HC_DCompute_Selection_By_Ray`
bool	`HC_Filter_Circumcuboid`
bool	`HC_Filter_Circumcuboid_By_Key`
bool	`HC_Filter_Circumcuboid_By_Path`
bool	`HC_Filter_Circumsphere`
bool	`HC_Filter_Circumsphere_By_Key`
bool	`HC_Filter_Circumsphere_By_Path`
bool	`HC_DFilter_Circumcuboid`
bool	`HC_DFilter_Circumcuboid_By_Key`
bool	`HC_DFilter_Circumcuboid_By_Path`
bool	`HC_DFilter_Circumsphere`
bool	`HC_DFilter_Circumsphere_By_Key`
bool	`HC_DFilter_Circumsphere_By_Path`
void	`HC_Set_Polygonal_Clip_Region`
void	`HC_DSet_Polygonal_Clip_Region`
void	`HC_Set_Complex_Clip_Region`
void	`HC_DSet_Complex_Clip_Region`
void	`HC_Show_Clip_Region`
void	`HC_DShow_Clip_Region`
void	`HC_Show_Clip_Region_Size`
void	`HC_DShow_Clip_Region_Size`
int	`HC_PShow_Net_Clip_Region`
int	`HC_PShow_Net_Clip_Region_Size`
int	`HC_DPShow_Net_Clip_Region`
int	`HC_DPShow_Net_Clip_Region_Size`
void	`HC_UnSet_Clip_Region`
void	`HC_Regenerate_LOD`
void	`HC_Regenerate_LOD_By_Key`
void	`HC_Set_Text_Region`
void	`HC_Show_Text_Region`
void	`HC_DSet_Text_Region`
void	`HC_DShow_Text_Region`
void	`HC_Show_Text_Region_Count`
void	`HC_UnSet_Text_Region`
bool	`HC_Compute_Screen_Extent`
bool	`HC_Compute_Screen_Extent_By_Pat`
bool	`HC_Compute_Screen_Extent_By_Key`
void	`HC_Set_Camera_Near_Limit`
bool	`HC_Show_Camera_Near_Limit`
bool	`HC_PShow_Net_Camera_Near_Limit`
void	`HC_UnSet_Camera_Near_Limit`
bool	`HC_PShow_One_Net_User_Opt_Len`
void	`HC_Show_One_User_Option_Length`
bool	`HC_PShow_One_Net_Uni_Opt_Len`
void	`HC_Show_One_Uni_Option_Length`
Key	`HC_Show_Original_Key`
Key	`HC_Show_Renumbered_Key`
double	`HC_Compute_Vector_Angle`
double	`HC_DCompute_Vector_Angle`
void	`HC_Set_Conditions`
void	`HC_UnSet_Conditions`
void	`HC_UnSet_One_Condition`
void	`HC_Set_Conditional_Action`
void	`HC_Show_Cond_Action_Types`
void	`HC_Show_One_Conditional_Action`
void	`HC_UnSet_Conditional_Actions`
void	`HC_UnSet_One_Conditional_Action`
Key	`HC_Conditional_Style`
Key	`HC_Conditional_Style_By_Key`
bool	`HC_Evaluate_Condition`
Key	`HC_Conditional_Include`
Key	`HC_Conditional_Include_By_Key`
void	`HC_Show_Conditions`
bool	`HC_PShow_Net_Conditions`
void	`HC_Show_Conditions_Length`
bool	`HC_PShow_Net_Conditions_Length`
void	`HC_Show_One_Condition`
bool	`HC_PShow_One_Net_Condition`
void	`HC_Show_Conditional_Include`
void	`HC_Show_Conditional_Style`
Key	`HC_Copy_Segment_With_Mapping`
void	`HC_Reverse_Contents_Search`
void	`HC_MShow_Vertex_Colors_By_Value`
void	`HC_MShow_Vertex_Colors_By_FInd`
void	`HC_MShow_Face_Colors_By_Value`
void	`HC_MShow_Face_Colors_By_FIndex`
void	`HC_MShow_Vertex_Normals`
void	`HC_MShow_Vertex_Parameters`
void	`HC_MShow_Vertex_Parameter_Size`
void	`HC_Set_Circular_Center`
void	`HC_Set_Circular_Center_By_Key`
void	`HC_DSet_Circular_Center`
void	`HC_DSet_Circular_Center_By_Key`
bool	`HC_Show_Circular_Center`
bool	`HC_DShow_Circular_Center`
void	`HC_MShow_Net_Vertex_Normals`
bool	`HC_Show_Error`
void	`HC_MSet_Vertex_Visibilities`
void	`HC_MUnSet_Vertex_Visibilities`
void	`HC_MShow_Vertex_Visibilities`
void	`HC_MSet_Face_Visibilities`
void	`HC_MUnSet_Face_Visibilities`
void	`HC_MShow_Face_Visibilities`
void	`HC_MSet_Specific_Vertex_Vis`
void	`HC_MUnSet_Specific_Vertex_Vis`
void	`HC_MShow_Specific_Vertex_Vis`
void	`HC_MSet_Specific_Face_Vis`
void	`HC_MUnSet_Specific_Face_Vis`
void	`HC_MShow_Specific_Face_Vis`
void	`HC_MUnSet_Face_Colors`
void	`HC_MUnSet_Vertex_Colors`
Key	`HC_Insert_Cutting_Section`
Key	`HC_DInsert_Cutting_Section`
void	`HC_Show_Cutting_Section`
void	`HC_Show_Cutting_Section_Count`
void	`HC_DShow_Cutting_Section`
void	`HC_Edit_Cutting_Section`
void	`HC_DEdit_Cutting_Section`
void	`HC_Compute_Triangulation`
void	`HC_Compute_Triangulation_Size`
bool	`HC_Compute_Polyline_From_Curve`
bool	`HC_DCompute_Polyline_From_Curve`
void	`HC_Compute_Pline_From_Crv_Size`
void	`HC_DCompute_Pline_From_Crv_Size`
void	`HC_Optimize_Segment_Tree`
void	`HC_Optimize_Segment_Tree_By_Key`
void	`HC_Show_Optimized_Mapping`
bool	`HC_PShow_Net_Texture`
bool	`HC_PShow_One_Net_Texture`
bool	`HC_PShow_Net_Shader`
bool	`HC_PShow_Net_Shaders`
bool	`HC_PShow_One_Net_Shader_Option`
void	`HC_Show_Priority_Range`
void	`HC_Delete_Specific_Shell_Points`
void	`HC_Delete_Specific_Shell_Faces`
void	`HC_MSet_Spec_Vert_Col_By_FIndex`
void	`HC_MSet_Spec_Vert_Col_By_Value`
void	`HC_MSet_Spec_Face_Col_By_FIndex`
void	`HC_MSet_Spec_Face_Col_By_Value`
void	`HC_MShow_Spec_Vert_Col_By_FInd`
void	`HC_MShow_Spec_Vert_Col_By_Value`
void	`HC_MShow_Spec_Face_Col_By_FInd`
void	`HC_MShow_Spec_Face_Col_By_Value`
void	`HC_MUnSet_Spec_Vertex_Colors`
void	`HC_MUnSet_Spec_Face_Colors`
int	`HC_Gather_Capping_Geometry`
Key	`HC_Generate_Shell_From_Geometry`
Key	`HC_Generate_Edges`
Key	`HC_Generate_Poly_From_Geometry`
void	`HC_Compute_Face_Neighborhood_Si`
void	`HC_Compute_Face_Neighborhood`
void	`HC_Show_Net_Normal`
void	`HC_Rollback_Ink`
Key	`HC_Reference_Geometry`
Key	`HC_Reference_Geometry_By_Key`
Key	`HC_Conditional_Reference`
Key	`HC_Conditional_Reference_By_Key`
Key	`HC_Show_Reference_Geometry`
Key	`HC_Show_Conditional_Reference`
void	`HC_Show_Reference_Geometry_Filt`
void	`HC_Begin_Open_Item_Search`
bool	`HC_Find_Open_Item`
void	`HC_Show_Open_Item_Count`
void	`HC_End_Open_Item_Search`
bool	`HC_PShow_Net_Color_Map_Length`
void	`HC_Show_Color_Map_Length`
void	`HC_Move_Key_By_Key`
void	`HC_Set_User_Data`
long	`HC_Show_One_User_Data`
long	`HC_Show_User_Data_Indices`
void	`HC_UnSet_One_User_Data`
long	`HC_PShow_One_Net_User_Data`
int	`HC_MShow_Vertex_Colors_With_Ex`
void	`HC_MUnSet_Vertex_Normals`
void	`HC_MUnSet_Face_Normals`
void	`HC_MUnSet_Vertex_Parameters`
void	`HC_MSet_Specific_Vertex_Normals`
void	`HC_MUnSet_Specific_Vert_Normals`
void	`HC_MShow_Specific_Vert_Normals`
void	`HC_MSet_Specific_Face_Normals`
void	`HC_MUnSet_Specific_Face_Normals`
void	`HC_MShow_Specific_Face_Normals`
void	`HC_MSet_Spec_Vertex_Parameters`
void	`HC_MShow_Spec_Vertex_Parameters`
void	`HC_MUnSet_Spec_Vert_Parameters`
void	`HC_MUnSet_Vertex_Colors2`
void	`HC_MUnSet_Spec_Vertex_Colors2`
int	`HC_MShow_Spec_Vert_Colors_W_Ex`
int	`HC_MShow_Face_Colors_With_Ex`
int	`HC_MShow_Spec_Face_Colors_W_Ex`
int	`HC_MShow_Vertex_Parameters_W_Ex`
int	`HC_MShow_Spec_Vertex_Params_W_E`
int	`HC_MShow_Vertex_Vis_W_Ex`
int	`HC_MShow_Spec_Vertex_Vis_W_Ex`
int	`HC_MShow_Face_Vis_W_Ex`
int	`HC_MShow_Spec_Face_Vis_W_Ex`
int	`HC_MShow_Vertex_Normals_W_Ex`
int	`HC_MShow_Spec_Vert_Normals_W_Ex`
int	`HC_MShow_Face_Normals_W_Ex`
int	`HC_MShow_Spec_Face_Normals_W_Ex`
Key	`HC_Include_Segment_Key_By_Key`
Key	`HC_Conditional_Include_Key_By_Ke`
void	`HC_Define_Named_Style`
void	`HC_Define_Named_Style_By_Key`
void	`HC_UnDefine_Named_Style`
Key	`HC_Show_Named_Style`
void	`HC_Begin_Named_Style_Search`
bool	`HC_Find_Named_Style`
void	`HC_Show_Named_Style_Count`
void	`HC_End_Named_Style_Search`
Key	`HC_PShow_Net_Named_Style`
Key	`HC_Named_Style_Segment`
Key	`HC_Conditional_Named_Style`
void	`HC_Show_Named_Style_Segment`
Key	`HC_Open_Segment_Key_By_Key`
Key	`HC_Style_Segment_Key_By_Key`
Key	`HC_Named_Style_Segment_By_Key`
Key	`HC_Conditional_Named_Style_By_Key`
void	`HC_Show_Conditional_Named_Style`
Key	`HC_Create_Segment_Key_By_Key`
void	`HC_Set_Default_Line_Styles`
void	`HC_Set_Default_Line_Styles_By_K`
void	`HC_Set_Default_Glyphs`
void	`HC_Set_Default_Glyphs_By_Key`
void	`HC_Set_Default_Shapes`
void	`HC_Set_Default_Shapes_By_Key`
Key	`HC_Reference_Geometry_Key_By_Ke`
bool	`HC_PShow_Net_Line_Style`
bool	`HC_PShow_Net_Line_Style_Size`
bool	`HC_PShow_Net_Glyph`
bool	`HC_PShow_Net_Glyph_Size`
bool	`HC_PShow_Net_Shape`
bool	`HC_PShow_Net_Shape_Size`
void	`HC_Generate_Error`
void	`HC_Commit_Proxy`
Key	`HC_Create_Proxy`
int	`HC_Inspect_Proxies`
void	`HC_Begin_Error_Handler_Search`
void	`HC_Begin_Exit_Handler_Search`
void	`HC_End_Error_Handler_Search`
void	`HC_End_Exit_Handler_Search`
bool	`HC_Find_Error_Handler`
bool	`HC_Find_Exit_Handler`
void	`HC_Show_Error_Handler_Count`
void	`HC_Show_Exit_Handler_Count`
Key	`HC_Compute_Subshell`
void	`HC_MSet_Specific_Edge_Vis`
void	`HC_MShow_Face_Normals`
void	`HC_MShow_Net_Face_Normals`
void	`HC_MShow_Specific_Edge_Vis`
void	`HC_MUnSet_Specific_Edge_Vis`
void	`HC_Show_Font_Info_By_Path`
void	`HC_Show_Reference_Keys`
void	`HC_Show_Reference_Keys_Count`
bool	`HC_PShow_Net_Line_Pattern_Exp`
bool	`HC_PShow_Net_Edge_Pattern_Exp`
int	`HC_Begin_Buffered_Selection`
int	`HC_Collect_Area_Samples`
int	`HC_Show_Sample_Max_Length`
bool	`HC_Find_Next_Sample`
void	`HC_End_Buffered_Selection`
void	`HC_UnSet_Priority`
void	`HC_Define_Highlight`
void	`HC_Define_Geometry_Highlight`
int	`HC_UnDefine_Highlight`
int	`HC_UnDefine_Geometry_Highlight`
void	`HC_Begin_Highlight_Search`
bool	`HC_Find_Highlight`
void	`HC_Show_Highlight_Count`
void	`HC_End_Highlight_Search`
void	`HC_Determine_Highlight_Status`
bool	`HC_Check_Double_Precision`
void	`HC_DSet_Camera`
void	`HC_DSet_Camera_By_Volume`
void	`HC_DSet_Camera_Position`
void	`HC_DSet_Camera_Target`
void	`HC_DSet_Camera_Up_Vector`
void	`HC_DSet_Camera_Field`
void	`HC_DShow_Camera`
void	`HC_DShow_Camera_By_Volume`
void	`HC_DShow_Camera_Position`
void	`HC_DShow_Camera_Target`
void	`HC_DShow_Camera_Up_Vector`
void	`HC_DShow_Camera_Field`
void	`HC_DOrbit_Camera`
void	`HC_DPan_Camera`
void	`HC_DRoll_Camera`
void	`HC_DDolly_Camera`
void	`HC_DZoom_Camera`
Key	`HC_DInsert_Text`
Key	`HC_DInsert_Text_Leader`
Key	`HC_DInsert_Text_With_Encoding`
void	`HC_DShow_Text`
void	`HC_DShow_Text_Leader`
void	`HC_DShow_Text_With_Encoding`
void	`HC_DEdit_Text_Leader`
Key	`HC_DInsert_Line`
void	`HC_DEdit_Line`
void	`HC_DShow_Line`
Key	`HC_DInsert_Marker`
void	`HC_DEdit_Marker`
void	`HC_DShow_Marker`
Key	`HC_DInsert_Polygon`
void	`HC_DEdit_Polygon`
void	`HC_DShow_Polygon`
Key	`HC_DInsert_Polyline`
void	`HC_DEdit_Polyline`
void	`HC_DShow_Polyline`
Key	`HC_DInsert_Shell`
void	`HC_DShow_Shell`
void	`HC_DShow_Shell_By_Tristrips`
void	`HC_DEdit_Shell_Points`
Key	`HC_DInsert_Circle`
Key	`HC_DInsert_Circle_By_Radius`
Key	`HC_DInsert_Circular_Arc`
Key	`HC_DInsert_Circular_Chord`
Key	`HC_DInsert_Circular_Wedge`
void	`HC_DEdit_Circle`
void	`HC_DEdit_Circle_By_Radius`
void	`HC_DEdit_Circular_Arc`
void	`HC_DEdit_Circular_Chord`
void	`HC_DEdit_Circular_Wedge`
void	`HC_DShow_Circle`
void	`HC_DShow_Circle_By_Radius`
void	`HC_DShow_Circular_Arc`
void	`HC_DShow_Circular_Chord`
void	`HC_DShow_Circular_Wedge`
Key	`HC_DInsert_Ellipse`
Key	`HC_DInsert_Elliptical_Arc`
void	`HC_DEdit_Ellipse`
void	`HC_DEdit_Elliptical_Arc`
void	`HC_DShow_Ellipse`
void	`HC_DShow_Elliptical_Arc`
Key	`HC_DInsert_Grid`
void	`HC_DShow_Grid`
void	`HC_DEdit_Grid`
Key	`HC_DInsert_Mesh`
void	`HC_DShow_Mesh`
void	`HC_DEdit_Mesh`
Key	`HC_DInsert_Image`
Key	`HC_DInsert_Compressed_Image`
void	`HC_DShow_Image`
void	`HC_DShow_Image_Size`
void	`HC_DShow_Compressed_Image`
void	`HC_DMove_Image`
Key	`HC_DInsert_Ink`
Key	`HC_DInsert_PolyCylinder`
void	`HC_DShow_PolyCylinder`
void	`HC_DEdit_PolyCylinder`
void	`HC_DEdit_PolyCylinder_With_Basis`
Key	`HC_DInsert_Cutting_Plane`
void	`HC_DShow_Cutting_Plane`
void	`HC_DEdit_Cutting_Plane`
Key	`HC_DInsert_Cylinder`
void	`HC_DShow_Cylinder`
void	`HC_DEdit_Cylinder`
Key	`HC_DInsert_Sphere`
void	`HC_DShow_Sphere`
void	`HC_DEdit_Sphere`
Key	`HC_DInsert_NURBS_Curve`
void	`HC_DShow_NURBS_Curve`
void	`HC_DEdit_NURBS_Curve`
Key	`HC_DInsert_NURBS_Surface`
void	`HC_DShow_NURBS_Surface`
void	`HC_DEdit_NURBS_Surface`
void	`HC_DEdit_NURBS_Surface_Points`
Key	`HC_DInsert_Local_Light`
void	`HC_DShow_Local_Light`
Key	`HC_DInsert_Spot_Light`
void	`HC_DShow_Spot_Light`
Key	`HC_DInsert_Area_Light`
void	`HC_DShow_Area_Light`
bool	`HC_DCompute_Coordinates`
bool	`HC_DCompute_Coordinates_By_Path`
void	`HC_DCompute_Transformed_Points`
Key	`HC_Compute_Boolean_Shell2`
Key	`HC_DCompute_Boolean_Shell`
void	`HC_DCompute_Optimized_Shell`
intptr_t	`HC_Memory_Usage_By_Key`
void	`HC_Apply_Attribute_Filter`
bool	`HC_Show_Attribute_Filter`
bool	`HC_Show_Attribute_Filter_Length`
void	`HC_Begin_Decimate_Shell`
void	`HC_End_Decimate_Shell`
Key	`HC_Decimate_Shell`

Detailed Description

Macro Definition

HC_PROTO_DEFINED

Function Documentation

void HC_Abort_Program(char const *message)

Function to create a map linking PrcIds and A3DEntities.

Prints an error message. Calls the defined exit handlers. Exits to the operating system with a final error status.

Provides an orderly way to terminate execution upon the discovery of an error.

DETAILS

A standard HOOPS fatal error sequence is initiated. First, the currently defined error handlers are called. The list presented includes Report_Error() (unless you’ve specified otherwise), which causes message to be printed out where the user can see it. Then, the currently defined exit handlers are called, usually including Reset_System() . Finally, the operating system is called, with an “error” exit status, to terminate program execution.

See also

HC_Exit_Program, HC_Define_Exit_Handler, HC_Define_Error_Handler, HC_Report_Error

Parameters: message – - A quoted string, or a string variable containing your error message. An empty string is permissible.

void HC_Append_Modelling_Matrix(float const array[])

Allows direct manipulation of the matrix transform applied against all picture elements and subsegments in a segment.

Appends the explicitly provided transformation to the cumulative modelling transform of the currently open segment, or to the named segment(s). The visual effect is that of the scene as it was, then this change. (The old array is multiplied on the left by this new array.)

DETAILS

Use this routine only if your program organizes and keeps track of the net transformations applied to your objects.

The array should be stored so the column varies faster than the row as you proceed through consecutive memory locations. In C and Pascal, the first index of the array is usually the row index and the second index is the column.

NOTES

If there was no previous transform, this operation becomes a plain Set_Modelling_Matrix().

The first, second, and third rows of the fourth column of array must be zero - no “perspective” transformation is allowed. The fourth row of the fourth column is usually 1.0 (it must not be zero.)

See also

HC_Set_Modelling_Matrix, HC_Rotate_Object, HC_Translate_Object, HC_Scale_Object, HC_Set_Camera, HC_Orbit_Camera.

RESTRICTIONS

Parameters: array – - Transform matrix provided by the user. Passed by reference in all languages. May need to be transposed in languages other than C.

void HC_DAppend_Modelling_Matrix(double const array[])

Similar to Append_Modelling_Matrix(), but accepts double-precision data.

See also

HC_Append_Modelling_Matrix

Parameters: array – - Transform matrix provided by the user. Passed by reference in all languages. May need to be transposed in languages other than C.

void HC_Append_Texture_Matrix(float const array[])

Allows direct manipulation of the matrix transform applied against all shell and mesh (u, v, w) vertex parameters and subsegments in a segment.

Appends the explicitly provided transformation to the cumulative texture transform of the currently open segment, or to the named segment(s). The visual effect is that of the scene as it was, then this change. (The old array is multiplied on the left by the new array.)

DETAILS

Use this routine if your program organizes and keeps track of the net transformations applied to your vertex parameters.

The array should be stored so the column varies faster than the row as you proceed through consecutive memory locations. In C and Pascal, the first index of the array is usually the row index and the second index is the column.

NOTES

If there was no previous transform, this operation becomes a plain Set_Texture_Matrix() .

The fourth row of the fourth column is usually 1.0 (it must not be zero.)

See also

HC_Set_Texture_Matrix, HC_Rotate_Texture, HC_Translate_Texture, HC_Scale_Texture.

RESTRICTIONS

Parameters: array – - Transform matrix provided by the user. Passed by reference always. May need to be transposed in languages other than C.

void HC_Begin_Alias_Search(void)

These routines recall the name of each alias.

This set of routines allows the user to “dump” all the aliases that exist in the database. It returns both the user defined aliases and those defined by the system (e.g.: “?include library”). It returns only the aliases names - to find out what their expansions are use Show_Alias(). For example:

DETAILS

Begin_Alias_Search ()
while (Find_Alias (alias)) {
    Show_Alias (alias, def)
    print (alias, def)
}
End_Alias_Search ()

prints all the known aliases names and their definitions. Begin_Alias_Search() initiates the search for each alias name.

Show_Alias_Count() finds out how many aliases will be returned. This is useful for determining the size of a data structure needed to store incoming items.

Find_Alias() retrieves the alias names, one at a time. The function returns false when all aliases have been returned.

End_Alias_Search() terminates the sequence and frees any involved memory.

If an alias search is in progress and an alias becomes undefined (via UnDefine_Alias() ), it will not be returned by subsequent calls to Find_Alias(). If an alias is added, it will not be returned until the next alias search begins.

NOTES

Show_Alias_Count() is only valid between Begin_Alias_Search() and End_Alias_Search(). It will always return the total number of aliases defined not the remaining number of aliases.

Alias searches can be nested. A user program can call Begin_Alias_Search() and look at the defined aliases without interfering with an alias search, which might have been activated by another portion of the program. When End_Alias_Search() is called, the previously active alias search (if any) becomes current.

See also

HC_Show_Alias, HC_Define_Alias, HC_Show_Pathname_Expansion

RESTRICTIONS

void HC_Begin_Callback_Name_Search(void)

Finds the names of all previously defined callback routines.

These routines are used to find all the callback name definitions existing within the database. For example,

DETAILS

Begin_Callback_Name_Search ()
    while (Find_Callback_Name (name))
        print (name)
End_Callback_Name_Search ()

prints all the known callback definitions. Begin_Callback_Name_Search() initiates the search for callback name definitions. If you need to know how many callback definitions will be returned (possibly to allocate a sufficiently large data structure to hold the results), call Show_Callback_Name_Count() after initiating the search.

Find_Callback_Name() returns the names, one by one. This function returns false when all the definitions have been returned.

End_Callback_Name_Search() terminates the search. This last step can be done anytime after initiating the search.

If a callback search is in progress and a callback becomes undefined (via UnDefine_Callback_Name() ), it will not be returned by subsequent calls to Find_Callback_Name() . If a callback definition is added, it will not be returned until the next callback search is initiated.

NOTES

Show_Callback_Name_Count() is only valid between Begin_Callback_Name_Search() and End_Callback_Name_Search() . It will always return the total number of callback names, not the remaining number of definitions.

Callback name searches can be nested. A user program can call Begin_Callback_Name_Search() and look at the defined callbacks without interfering with a callback search, which might be in progress. When End_Callback_Name_Search() is called, the previously active callback search is resumed.

See also

HC_Define_Callback_Name, HC_Show_Callback_Name.

void HC_Begin_Color_Name_Search(void)

These routines recall all the defined color names.

These routines are used to find all the color definitions in the database. For example,

DETAILS

Begin_Color_Name_Search ()
    while (Find_Color_Name (first, second, third)
        print (first, second, third)
End_Color_Name_Search ()

prints all the known names, in the style in which they were originally defined. Begin_Color_Name_Search() initiates the search for color names.

If you need to know how many color definitions will be returned (possibly for allocating a data structure to hold them) call Show_Color_Name_Count() after initiating the search.

Find_Color_Name() returns the names (one set at a time). The function returns false when all color names have been returned.

End_Color_Name_Search() terminates the process and frees any involved memory. This last step can be done any time after the initial call to Begin_Color_Name_Search().

If you want to examine the color name definitions, call Parse_String() (to take out the commas) on the results of Find_Color_Name(). Then call Show_Color_Name() on each name.

NOTES

After calling Begin_Color_Name_Search(), if a color becomes undefined (via UnDefine_Color_Name() ), subsequent calls to Find_Color_Name() will not return it. If a color is redefined, the new definition will be returned. If a new color is defined, it will not be returned in this search sequence.

Show_Color_Name_Count() is only valid between Begin_Color_Name_Search() and End_Color_Name_Search() . It will always return the total number of colors defined, not the remaining number of color definitions.

Color name searches can be nested. A user program can call Begin_Color_Name_Search() and look at the defined color names without interfering with a color name search, which might have been activated by another portion of the program. When End_Color_Name_Search() is called, the previously active color name search (if any) becomes current.

See also

HC_Define_Color_Name, HC_Show_Color_Name, HC_Parse_String

void HC_Begin_Contents_Search(char const *segment, char const *filter)

These routines are used to “dump” the contents of a segment or certain types of geometry.

Many user applications must manipulate the geometry in the database to perform some type of analysis. For example, if a program needs to calculate the areas of all polygons in a segment, it would need to know the coordinates of the points in each polygon. A contents search (specifically, Find_Contents()) can be used to retrieve the keys of all of the polygons, and then Show_Polygon() can be used to extract the points.

DETAILS

In a contents search, Begin_Contents_Search() initiates and defines the search. Only the types specified in filterare used in the search, and only the segment or geometry specified in segment are checked.

Show_Contents_Count() determines the number of entities returned. This is useful for determining the size of a data structure needed to store the incoming items.

Find_Contents() returns entities, one at a time, from the selected segment or geometry. Find_Contents returns a type (i.e. “window frame”) and, if appropriate, a key. (Geometry, segments, includes, and styles have keys. Attributes do not have keys.) The return value is false when all items have been returned.

End_Contents_Search() terminates the search sequence.

As with the other search routines, Begin_Contents_Search() operations can be nested. This feature can be used, for example, to “walk the tree” as sub-segments are encountered. A call to End_Contents_Search() terminates the current search context (segment specification and filter) and reactivates the previously active context (if any).

The segment parameter can take a number of valid location specifications including aliases, wildcards, and paths, as explained in the HOOPS/3dGS Programming Guide section on :ref:segment name syntax <prog_guide/3dgs/01_3_database_dbase_structure:Segment name syntax>. The following are examples of valid usage:

“.” Searches the currently open segment.
“..” Searches the parent of the currently open segment.
“…” Searches the currently open segment and its child segments.
“….” Searches the currently open segment, its children, and any include segments below the current segment.
“?picture/model” Searches the segment “model”.
“?picture/model/…” searches the segment named ‘model’ and all of its subsegments.
“?picture/model/….” Searches the segment named ‘model’, all of its children, and any include segments below ‘model’.
“/…/model*” Searches all segments in the entire tree starting with ‘model’, but not their subsegments.

The filter parameter specifies the types of objects that will be returned by later calls to Find_Contents(). The types are passed in a list of the form “type, type…”, where each type is one of the following:

Geometry that can be inserted such as “images, lights, lines, markers, meshes, polygons, polylines, shells, string cursors, text”.
One of the attributes that can be set such as “color”, “marker size”, “color map”, “streaming mode”, etc. Attribute filters may be refined by adding sub-options to the string, such as “color=(lines)”, “user options = cost” or “visibility=faces”.
The word “geometry” matches all types of geometry.
The word “attributes” matches all attributes.
The word “style” matches style references.
The types “segment” and “include” match, respectively, child segments and “include references” to segments.
The word “subsegment” matches “segment” and “include”.
The word “inked line” selects the “currently being inked in” polyline (if any).
The word “ordered” returns only geometry brought to the front by Bring_To_Front() . The items are returned in drawing order. Successively returned items are drawn on top of previously returned items when the scene is updated.
The word “everything”, matches all types.
The word “self”, matches the subsegments themselves in a recursive search. This differs from the “subsegment” keyword in that it returns the parent instead of the children.
Any of the above types with “no” in front of them. For example: “everything, no geometry, no windows, no color maps” selects all types except windows, color maps, and all types of geometry. If specifications overlap (as in “geometry, no lines”), the last specification wins.
The word “hardware resources” matches display lists, textures, and vertex arrays that exist on the video card’s cache.
The word “follow references” means the search will dig through references as part of the search. Without it, you’d have to search for references explicitly, find what they’re pointing at and do a new search there.

The plural “s” after each type is optional. The types can be in any combination of upper and lowercase. Leading and trailing blanks are not significant. A blank string is equivalent to “everything”.

Additional types (meanings should be self-explanatory) accepted by this function are:

“distant light”, “local light”, “spot light”, “area light”, “includer”, “styler”, “style”, “color”, “callback”, “camera”, “clip

region”, “handedness”, “selectability”, “visibility”, “window”, “window frame”, “color map”, “driver”, “driver options”, “edge

pattern”, “edge weight”, “face pattern”, “heuristics”, “line pattern”, “line weight”, “marker size”, “marker symbol”, “metafile”, “modelling matrix”, “rendering options”, “text alignment”, “text font”, “text leader”, “text path”, “text spacing”, “texture matrix”, “user value”, “window pattern”, “texture definition”, “local texture”, “glyph definition”, “line pattern

definition”, “line style definition”, “condition”, “streaming mode”, “circle”, “circular arc”, “circular chord”, “circular

wedge”, “cutting plane”, “cutting section”, “light”, “ellipse”, “elliptical arc”, “grid”, “line”, “marker”, “mesh”, “image”, “pixel array”, “polyline”, “polygon”, “shell”, “string cursor”, “text”, “nurbs curve”, “nurbs surface”, “cylinder”, “polycylinder”, “sphere”, “include”, “reference geometry”, “user options”

The following code example sums the areas of all polygons in all segments that contain the word “plate”. It assumes the existence of a user written function that returns the area of a polygon given its key.

 sum = 0.0 Begin_Contents_Search
*("/...*plate*", "polygons") while (Find_Contents (type, poly)) sum = sum + polygon_area(poly) End_Contents_Search () 

(The “type” variable in this example will always be given the value “polygon”.)

The segment name passed to Begin_Contents_Search() can contain wildcards, a list of segments or both. In this case, subsequent calls to Find_Contents() do not distinguish which segment contains each object. Use Show_Owner_By_Key() to determine this. Also, when multiple segments are specified, the type “ordered” does not distinguish which objects in the segments will be drawn first.

The returned types are entirely lowercase and singular, for example: “line”, “selectability”, “polygon”. Normally, you would look at the type and make other calls ( Show_Visibility() , Show_Polyline() , etc.) to get more details about the object whose key was returned.

If an object satisfying the target specification is deleted while a segment search is in progress, it will not be returned by Find_Contents() . If a segment is renamed, the new name will be returned. If geometry is moved to a new segment, its key will be returned even if the new segment name no longer matches the original search specification. If an object is created after a call to Begin_Contents_Search(), it will not be returned in the current sequence of Find_Contents() calls.

NOTES

Show_Contents_Count() is only valid between Begin_Contents_Search() and End_Contents_Search(). It will always return the total number of items not the remaining number of items.

The inked line returned from a streaming segment will contain only the portion added since the last “Set” command changed any attribute in that segment.

“When “hardware resources” are found by Begin_Contents_Search, Find_Contents always return -1. In other words, hardware

resources have no keys associated with them. Shells and Meshes can be opened and have their “hardware resources” flushed, but

all other types of geometry (e.g. lines, polylines polycylinders and images) must have their “hardware resources” flushed from either their owning segment or some segment above.

See also

HC_Begin_Segment_Search, HC_Show_Existence, HC_Show_Key_Type, HC_Show_Segment, HC_Show_Owner, HC_Show_Polyline, HC_Show_Shell, HC_Show_Marker.

Parameters

segment – - A string specifying the location(s) of the search.
filter – - List of the types of objects you ‘re interested in.

void HC_Begin_Font_Search(char const *display, char const *filter)

Finds the names of all the fonts available on a particular device.

Begin_Font_Search() initiates and defines the search. Only the types specified in filter are searched for.

DETAILS: A font search allows you to find out what fonts are available on a given display.

Show_Font_Count() determines the number of font names returned. This is useful for determining the size of a data structure needed to store the incoming items.

Find_Font() returns names, one at a time, from the selected display. The return value becomes false when all items have been returned.

End_Font_Search() terminates the search sequence. As with the other search routines, the Begin_Font_Search() operations can be nested.

The following choices are available for filter:

“Generic” tells you which of the generic font names (see Set_Text_Font() ) are available - in at least one size.

“Specific” tells you which individual fonts are available, with the names coming back in the style of the local system (for example, the operating system).

“Defined” tells you which user defined fonts are available, with the names coming back in the previously defined form.

“Family” or “families” tells you which name the system, or HOOPS, has picked to refer to the available sizes of a single typeface.

Any combination of choices can be given. Separate by commas. Uppercase versus lowercase is not important.

If you need more than the name of a font, call Show_Font_Info() to get additional details.

A simple coding example is:

Begin_Font_Search ("?Picture", "generic")
while (Find_Font (name))
    print ("Yes,?Picture has: ", name)
End_Font_Search ()

If the device is not operating, Begin_Font_Search() might force a call to Update_Display() to get it started. See the note at the bottom of Show_Device_Info() for more information.

NOTES

Show_Font_Count() is only valid between Begin_Font_Search() and End_Font_Search(). It will always return the total number of items, not the remaining number of items.

See also

HC_Define_Font, HC_Show_Font, HC_Show_Font_Info, HC_Set_Text_Font, HC_Show_Device_Info.

Parameters

display – - Name of the segment connected to the display of interest. Often “?Picture” or “?Hardcopy”.
filter – - A list of restrictions on the fonts of interest.

void HC_Begin_Glyph_Search(void)

These routines recall all the defined glyph names.

These routines are used to find all of the glyph definitions that exist in the database. For example,

DETAILS

Begin_Glyph_Search ()
while (Find_Glyph (the_name))
    Show_Glyph(the_name, definition)
End_Glyph_Search ()

retrieves all the known names, in the style in which they were originally defined. If you need to know how many glyph definitions will be returned (possibly for allocating a data structure to hold them) call Show_Glyph_Count() after initiating the search.

Find_Glyph() returns the names (one at a time). The function returns false when all glyph names have been returned.

End_Glyph_Search() terminates the process and frees any involved memory. This last step can be done any time after the initial call to Begin_Glyph_Search().

After calling Begin_Glyph_Search(), if a glyph becomes undefined (via UnDefine_Glyph()), subsequent calls to Find_Glyph() will not return it. If a glyph is redefined, the new definition will be returned. If a new glyph is defined, it will not be returned in this search sequence.

NOTES: If you want to examine the glyph name definitions, call Show_Glyph() on the results of Find_Glyph() .

Show_Glyph_Count() is only valid between Begin_Glyph_Search() and End_Glyph_Search(). It will always return the total number of glyphs defined as opposed to the remaining number of glyph definitions.

Glyph name searches can be nested. A user program can call Begin_Glyph_Search() and look at the defined glyph names without interfering with a glyph name search that might already have been activated by another portion of the program. When End_Glyph_Search() is called, the previously active glyph name search (if any) becomes current.

See also

HC_Define_Glyph, HC_Show_Glyph, HC_Parse_String

void HC_Begin_Line_Style_Search(void)

These routines recall all the defined line style names.

These routines are used to find all of the line style definitions that exist in the database. For example,

Begin_Line_Style_Search ()
while (Find_Line_Style (the_name))
    Show_Line_Style(the_name, definition)
End_Line_Style_Search ()

DETAILS

retrieves all the known names, in the style in which they were originally defined. If you need to know how many line style definitions will be returned (possibly for allocating a data structure to hold them) call Show_Line_Style_Count() after initiating the search.

Find_Line_Style() returns the names (one at a time). The function returns false when all line style names have been returned.

End_Line_Style_Search() terminates the process and frees any involved memory. This last step can be done any time after the initial call to Begin_Line_Style_Search().

If you want to examine the line style name definitions, call Show_Line_Style() on the results of Find_Line_Style() After calling Begin_Line_Style_Search() , if a line style becomes undefined (via UnDefine_Line_Style() ), subsequent calls to Find_Line_Style() will not return it. If a line style is redefined, the new definition will be returned. If a new line style is defined, it will not be returned in this search sequence.

NOTES

Show_Line_Style_Count() is only valid between Begin_Line_Style_Search() and End_Line_Style_Search() . It will always return the total number of line styles defined as opposed to the remaining number of line style definitions.

Line_Style name searches can be nested. A user program can call Begin_Line_Style_Search() and look at the defined line style names without interfering with a line style name search that might already have been activated by another portion of the program. When End_Line_Style_Search() is called, the previously active line style name search (if any) becomes current.

See also

HC_Define_Line_Style, HC_Show_Line_Style, HC_Parse_String

void HC_Begin_Open_Segment_Search(void)

Returns the pathnames of all open segments.

These routines are used to indicate all the segments that have been opened but not closed. A call to Begin_Open_Segment_Search() initiates the process. Each call to Find_Open_Segment() returns the pathname of a single open segment starting with the currently open segment (the most recently opened segment) and ending with the least recently opened segment. End_Open_Segment_Search() terminates the sequence and allows another series of open segment searches to be initiated.

DETAILS

Once Begin_Open_Segment_Search() is called, Show_Open_Segment_Count() can be used to return the total number of open segments. This routine is useful for sizing an array large enough to hold all the pathnames returned by a sequence of calls to Find_Open_Segment() .

Once Begin_Open_Segment_Search() is called, all currently open segments will be returned by Find_Open_Segment() even if they are closed in the meantime. However, if any open segments are closed and then deleted, they will not be returned. Any open segments that are renamed will be returned with the new name.

NOTES: You can use these routines with no segments open. The first call to Find_Open_Segment() will just return false.

Show_Open_Segment_Count() is only valid between Begin_Open_Segment_Search() and End_Open_Segment_Search() . It will always return the total number of open segments, not the remaining number of open segments.

Open segment searches can be nested. A user program can call Begin_Open_Segment_Search() and look at the open segments without interfering with an open segment search, which might have been activated by another portion of the program. When End_Open_Segment_Search() is called, the previously active open segment search (if any) becomes current.

See also

HC_Begin_Contents_Search, HC_Begin_Segment_Search, HC_Open_Segment.

void HC_Begin_Segment_Search(char const *segspec)

Finds all segments matching a search specification.

Begin_Segment_Search() initiates the search by specifying where to start looking for segments.

DETAILS: The segment search routines provide the ability to determine the current segment structure of the database.

Show_Segment_Count() lets a program anticipate how many segments names will be returned from a sequence of calls to Find_Segment() in order that sufficient space may be allocated to receive them. Count is the total number of matching segments.

Find_Segment() is the routine that returns, one at a time, the segments which matched the specification given in Begin_Segment_Search(). When all segments have been returned, its function value becomes false.

End_Segment_Search() terminates the search sequence and reactivates any previously active segment search.

The segspec parameter can take a number of valid segment name specifications including aliases, wildcards, and paths, as explained in the HOOPS/3dGS programming guide section 1.2.6 “Segment-Name Syntax”. Wildcards in the segment specification will typically match more than one segment in the database. The following examples are valid usages:

“*” Returns the currently open segment and all children, but no grandchildren.
“.” Returns the currently open segment.
“..” Returns the parent of the currently open segment.
“…” Returns the currently open segment, and all subsegments.
“….” Returns the currently open segment, all subsegments, and any include segments below the current segment.
“?picture/model” Returns the segment “model”.
“?picture/model/..” Returns “?picture”.
“?picture/model/…” Returns the segment named ‘model’ and all of its subsegments.
“?picture/model/….” Returns the segment named ‘model’, all of its children, and any include segments below ‘model’.
“/…/model*” Returns all segments in the entire tree starting with ‘model’, but not their subsegments.
“/…/model/….” Searches all segments in the entire tree named ‘model’, their children, and any include segments below them.

The Begin_Segment_Search() operations can be nested. This allows a program to “walk the tree” as in the following recursive example (written in C) which prints the names of all the children in the subtree of a given segment:

level = 0
print_children (segment) {
    Open_Segment (segment)
        Begin_Segment_Search ("*")
        while (Find_Segment (child)) {
            Parse_String (child, "/", -1, pathname)
            print (level, pathname)
            level = level + 1
            print_children (pathname)
            level = level - 1
        }
        End_Segment_Search ()
    Close_Segment ()
}

This example could also have been written using the “contents search” routines, replacing “Begin_Segment_Search (“*”)” with “Begin_Contents_Search (“.”, “segments”)”, and so on.

If a search is in progress and a segment satisfying the target specification is deleted, it will not be returned by subsequent calls to Find_Segment() . If a segment is renamed, the new name will be returned. If a segment is created, it will not be returned in the current sequence of Find_Segment() calls.

NOTES: If no segments are found that match the specification, the first call to Find_Segment() returns false.

Show_Segment_Count() must be called between Begin_Segment_Search() and End_Segment_Search() . It will always return the total number of segments, not the remaining number of segments.

See also

HC_Begin_Contents_Search, HC_Begin_Open_Segment_Search, HC_Show_Existence, HC_Open_Segment.

Parameters: segspec – - A specification, often including wildcards, of the segment(s) to be searched for. Passed by reference always

void HC_Begin_Shader_Search(char const *search)

These routines recall the name of each shader.

…prints all the known shader names, their options and source. Begin_Shader_Search() initiates the search for each shader name.

Find_Shader() retrieves the shader names, one at a time. The function returns false when all shaders have been returned.

End_Shader_Search() terminates the sequence and frees any involved memory.

See also

HC_Show_Shader, HC_Define_Shader

NOTES: If a shader search is in progress and an shader becomes undefined via UnDefine_Shader(), it will not be returned by subsequent calls to Find_Shader(). If a shader is added, it will not be returned until the next shader search is begun.

Parameters

search –

- A specification of which custom shader implementation to search for: either “legacy” or “modern”.

\par DETAILS

This set of routines allows the user to “dump” all the shaders that exist in the database. It returns only the shader names. To find the details for each shader use Show_Shader() . For example

Begin_Shader_Search () while (Find_Shader (shader))
           {
               Show_Shader (shader, def, source)
               print (shader, def, source)
           }
           End_Shader_Search ()

void HC_Begin_Shape_Search(void)

void HC_Begin_Texture_Search(void)

These routines recall all the defined texture names.

Begin_Texture_Search ()
while (Find_Texture (the_name))
    Show_Texture(the_name, definition)
End_Texture_Search ()

DETAILS: These routines are used to find all of the texture definitions that exist in the database. For example,

retrieves all the known names, in the style in which they were originally defined. If you need to know how many texture definitions will be returned (possibly for allocating a data structure to hold them) call Show_Texture_Count() after initiating the search.

Find_Texture() returns the names (one at a time). The function returns false when all texture names have been returned.

End_Texture_Search() terminates the process and frees any involved memory. This last step can be done any time after the initial call to Begin_Texture_Search() .

After calling Begin_Texture_Search() , if a texture becomes undefined (via UnDefine_Texture() ), subsequent calls to Find_Texture() will not return it. If a texture is redefined, the new definition will be returned. If a new texture is defined, it will not be returned in this search sequence.

NOTES: If you want to examine the texture name definitions, call Show_Texture() on the results of Find_Texture() .

Show_Texture_Count() is only valid between Begin_Texture_Search() and End_Texture_Search() . It will always return the total number of textures defined as opposed to the remaining number of texture definitions.

Texture name searches can be nested. A user program can call Begin_Texture_Search() and look at the defined texture names without interfering with a texture name search that might already have been activated by another portion of the program. When End_Texture_Search() is called, the previously active texture name search (if any) becomes current.

See also

HC_Define_Texture, HC_Show_Texture, HC_Parse_String.

void HC_Begin_Local_Texture_Search(void)

Begins a texture search on the currently open segment.

Begin_Local_Texture_Search() is similar to Begin_Texture_Search() , but operates only on the currently open segment. To find all textures with this function, use the following method:

 HC_Begin_Contents_Search("/...", "segments"); while
(HC_Find_Contents(type, &segKey)) { HC_Open_Segment_By_Key(segKey); HC_Show_Segment (segKey, pathname);
    HC_Begin_Contents_Search (".", "attributes");
    while (HC_Find_Contents(type, &tempKey)){
        if (!strcmp (type, "texture definitions")) {
            HC_Begin_Local_Texture_Search();
            HC_Show_Texture_Count(&texture_count);
            HC_Find_Texture (texture_name);
        }
    }
}
HC_End_Contents_Search();

DETAILS

See also

HC_Begin_Texture_Search

NOTES: This behaves in a very similar fashion to Begin_Texture_Search() except that it only looks for locally defined textures. Also, since local textures are connected to a segment you must provide a segment from which the search should begin.

void HC_Bring_To_Front(char const *segment)

Deprecated:: This function has been deprecated. It is superseded by setting the hsra rendering option to priority.

If the subject of a call to Bring_To_Front() , specified either by key or by name, is a segment that has a Window attribute, then you’re effectively asking to rearrange windows. A windowed segment that lies within a windowed segment is always drawn “on top” of the containing window. But when windowed segments lie side-by-side in the segment tree - when neither window is the owner of the other - the situation becomes ambiguous. If such windows don’t overlap no problem arises. If they do overlap, Bring_To_Front() allows for making a choice. Set_Window() automatically calls Bring_To_Front() for each newly-created window, so the default is “newest in front.” You might make an explicit call when, for example, the user’s interest has shifted from one window to another. This is often indicated by some action such as touching a rear window. In summary, Bring_To_Front() can be used to specify the precedence of overlapping sibling windows.

DETAILS: This function forces a particular drawing order onto a collection of geometric primitives. Since it does not change depth values, however, it has only minor effects on scenes with hidden surface removal algorithms (e.g. z-buffer, the default).

If, on the other hand, the subject of a call to Bring_To_Front() is something other than a windowed segment - if it’s geometry or a non-windowed segment - then you’re forcing a particular drawing order onto the system. You would do this if you want to manually describe what’s to have the appearance of being in front. Forcing a drawing order is sometimes more efficient than using the system’s hidden-surface algorithm. It might be suitable for a paint program in which the user selects precedence, or useful for putting “annotations” on a scene that is otherwise all hidden-surfaced. You should not use Bring_To_Front() if you don’t really care about the ordering. The system works more efficiently if it is permitted to order objects as it pleases.

Using Bring_To_Front() on 3-D geometry and nonwindowed segments only works within those segments where the “hidden surfaces” heuristic is not in effect. Hidden surfaces take priority over bring-to-front. So, to mix hidden-surface items and bring-to-front items in the same scene, do something like the following:

Open_Segment ("window")
Set_Heuristics ("no hidden surfaces")
Open_Segment ("A")
    Set_Heuristics ("hidden surfaces")
    // regular hidden-surface picture, as needed
Close_Segment ()
Open_Segment ("B")
    Set_Heuristics ("hidden surfaces")
    // regular hidden-surface picture, as needed
Close_Segment ()
// now make "A" completely in front of "B"...
Bring_To_Front ("A")
Close_Segment ()

Note that “A” or “B” could have elected to continue with “no hidden surfaces”. It might also make sense, depending on what “A” and “B” are, to turn off lighting visibility in one or the other. In addition, Bring_To_Front() can only be applied to siblings “A” versus “B.” Bring_To_Front() does not apply to parent-child relationships.

This function can help resolve situations that arise with z-buffering where two surfaces have identical depth values but it is known which is supposed to be on top. For example, highlighting can be done this way, by drawing an extra copy with different attributes. This, combined with Control_Update() can be a powerful technique to highlight and de-highlight subsets of shells without ever incurring full updates.

NOTES: If the object of the bring-to-front is a non-windowed segment or an include reference, the effect is of bringing forward that collection of geometry as a whole.

Once something has been brought-to-front there is no simple way to put it back where it was. More objects can be put in front of the first, though, and the system will remember the entire ordering.

If the wildcard construction is used on Bring_To_Front() (segment) and there are conflicts, the system’s choice of who really gets to be the one in front will not be predictable.

Entities within a streaming-mode segment can not be “brought-to-front”.

Bring_To_Front() only works on the local level of the segment tree. If window A contains window B which contains window C, a bring-to-front of C will make C the foremost of all the windows within B. It won’t make B foremost of the windows within A. If you want that to be true say so, separately.

If polygons are displayed with no explicit drawing order (without hidden surfaces and without an explicit Bring_To_Front() ) and a “scoped” refresh happens (for example, a window-system window is removed from on top of half the HOOPS scene), the scoped refresh may redraw its part of the scene in a different order than the original. This causes an obvious suture line.

RESTRICTIONS

See also

HC_Set_Window, HC_Set_Heuristics, HC_Set_Streaming_Mode, HC_Set_Camera, HC_Set_Visibility.

Parameters: segment – - Name of the segment(s) to be shuffled forward.

void HC_Bring_To_Front_By_Key(Key key)

Similar to Bring_To_Front(), but operates on an object referenced by an HC_KEY.

Deprecated:: This function is deprecated.

See also

HC_Bring_To_Front()

Parameters: key – - Open_Segment() , or any Insert routine.

void HC_Close_Edge(void)

Closes the session that began with an opening call to Open_Edge().

See also

HC_Open_Edge()

void HC_Close_Face(void)

Closes the session that began with an opening call to Open_Face().

See also

HC_Open_Face()

void HC_Close_Geometry(void)

Closes the session that began with an opening call to Open_Geometry().

See also

HC_Open_Geometry()

void HC_Close_LOD(void)

Closes the session that began with an opening call to Open_LOD().

See also

HC_Open_LOD()

void HC_Close_Region(void)

Closes the session that began with an opening call to Open_Region().

See also

HC_Open_Region()

void HC_Close_Segment(void)

Closes the currently open segment.

See also

HC_Open_Segment, HC_Rename_Segment, HC_Flush_Contents, HC_Reset_System

DETAILS: Closes the currently open segment (i.e., the most recently opened segment), which is then no longer ready and available for “Insert” and “Set” operations. If there was a previously open segment, that segment becomes current once again. There must (eventually) be a matching Close_Segment() for every Open_Segment() , but in between as many Open’s and Close’s and even Update’s as you please can occur.

void HC_Close_Vertex(void)

Closes the session that began with an opening call to Open_Vertex().

See also

HC_Open_Vertex()

bool HC_Compile_Shader(int key_count, Key const path_keys[], char const *options)

Defines a section of code that will be injected into HOOPS 3DF shaders.

The geometry suboption needs to be the type of geometry which we want to see the shader for, optionally followed by a filter to limit generation to a particular set of primitives. For example, you could specify “geometry = (shell = triangles)” to get only the triangle shader for the shell, “geometry = (shell = (lines, points))” to get only the lines and points shaders for the shell, or “geometry = shell” to get triangle, lines, and points shaders for shells. The following is a list of geometry choices with the primitive types they may generate:

“nurbs curve” - “lines”
“elliptical arc” - “lines”
“circular arc” - “lines”
“line” - “lines”
“polyline” - “lines”
“polygon” - “triangles”, “lines”
“circular chord” - “triangles”, “lines”
“circular wedge” - “triangles”, “lines”
“ellipse” - “triangles”, “lines”
“circle” - “triangles”, “lines”
“marker” - “points”
“shell” - “triangles”, “lines”, “points”
“mesh” - “triangles”, “lines”, “points”
“cylinder” - “triangles”, “lines”
“polycylinder” - “triangles”, “lines”
“sphere” - “triangles”, “lines”
“nurbs surface” - “triangles”, “lines”
“text” - “triangles”, “lines”
“grid” - “triangles”, “lines”, “points”
“infinite line” - “lines”
“image” - “triangles”

Supported Options:: geometry, stage, vertex format
DETAILS: [all] geometry

[all] stage [vertex | pixel]

The stage suboption will be either vertex or pixel if you wanted to restrict the shaders that are generated to a particular stage.

vertex format

The vertex format suboption can have the following options:

“position” - [on | off]
“double position” - [on | off]
“normals” - [on | off]
“diffuse” - [on | off]
“specular” - [on | off]

Default activated options are : position, normals and diffuse.

See also

HC_Show_Compilation_Results_Size, HC_Show_Compilation_Results

Parameters

key_count – - The number of keys in the path
path_keys – - An array of keys, from the target segment up to a driver. Also possible to pass a single segment key
options – - A quoted string or a string variable containing a list of the desired options

Returns

true if it was able to find a custom shader on the given path for either the vertex or pixel shader and geometry, construct the shader source for any relevant primitive types, invoke the shader compile function, and the compilation is successful. Returns false otherwise.

bool HC_Compute_Circumcuboid(char const *segment, Point *min, Point *max)

Returns points defining a cuboid that circumscribes the geometry within a segment.

This function returns the axis-aligned bounding cuboid associated with a database entity. The bounding volume returned is computed on demand - it does not reflect the bounding volume stored at the segment, if any. The routine, Show_Bounding_Cuboid() , can be used for that purpose. The volume returned is expressed in oru.

DETAILS

Compute_Circumcuboid, the standard variant, allows only for segments. The By_Key variant, however, allows for keys that refer to any sort of geometry (in addition to segments). The standard variant allows for the normal wildcards associated with a segment specification.

The By_Key variant will fail if the specified key in variant does not refer to anything valid. The standard variant will fail if the specified segment in the does not match at least one segment, or all matched segments are empty of any geometry.

Transform-dependent geometry (e.g. markers, text) contributes only its insertion point. A reasonable way to handle markers would be to add a small pad to the min and max result. Special handling is needed to account for text, however. HOOPS/MVO (distributed as open source) contains a good example of that special handling (hint: it involves Compute_Text_Extent() ).

Temporary geometry created “on the fly” in the midst of I.M. callbacks will never contribute to any bounding volumes. The computed bounding volume will be with respect to geometry that has been inserted into the database. When called on a large segment tree, this function can become expensive, so use sparingly.

See also

HC_Compute_Circumsphere, HC_Compute_Coordinates, HC_Compute_Transform, HC_Show_Bounding_Info, HC_Show_Bounding_Cuboid,

NOTES

Parameters

segment – - Segment name to use for the calculation.
min – - The lower-most nearest diagonal point (xmin,ymin,zmin) of the cuboid to encompass the geometry contained within the segment. Returned to user. Passed by reference in all languages.
max – - The upper-most distant diagonal point (xmax,ymax,zmax) of the cuboid to encompass the geometry contained within the segment. Returned to user. Passed by reference in all languages.

Returns

success

bool HC_Compute_Circumcuboid_By_Key(Key key, Point *min, Point *max)

Similar to Compute_Circumcuboid(), but operates on an object referenced by an HC_KEY.

See also

HC_Compute_Circumcuboid()

Parameters

key – - Key of the segment used for the calculation.
min – - The lower-most nearest diagonal point (xmin, ymin, zmin) of the cuboid to encompass the geometry contained within the segment. Returned to user. Passed by reference in all languages.
max – - The upper-most distant diagonal point (xmax, ymax, zmax) of the cuboid to encompass the geometry contained within the segment. Returned to user. Passed by reference in all languages.

Returns

success

bool HC_Compute_Circumsphere(char const *segment, Point *center, float *radius)

Returns points defining a sphere that circumscribes the geometry within a segment.

See also

HC_Compute_Circumcuboid, HC_Compute_Coordinates, HC_Compute_Transform, HC_Show_Bounding_Info, HC_Show_Bounding_Cuboid, HC_Show_Bounding_Sphere.

DETAILS The volume for Compute_Circumsphere() is a sphere instead of a: cuboid. For more information refer to the discussion for Compute_Circumcuboid() .

Parameters

segment – - Segment name to use for the calculation.
center – - The center position of a sphere that encompasses the geometry contained within the segment. Returned to user. Passed by reference in all languages.
radius – - The radius length of the encompassing sphere. Returned to user. Passed by reference in all languages.

Returns

success

bool HC_Compute_Circumsphere_By_Key(Key key, Point *center, float *radius)

Similar to Compute_Circumsphere(), but operates on an object referenced by an HC_KEY.

See also

HC_Compute_Circumsphere()

Parameters

key – - Key of the segment or geometry to be used for the calculation.
center – - The center position of a sphere that encompasses the geometry contained within the segment. Returned to user. Passed by reference in all languages.
radius – - The radius length of the encompassing sphere. Returned to user. Passed by reference in all languages.

Returns

success

bool HC_DCompute_Circumcuboid(char const *segment, DPoint *min, DPoint *max)

Similar to Compute_Circumcuboid, but accepts double-precision parameters.

Parameters

segment – - Segment name to use for the calculation.
min – - The lower-most nearest diagonal point (xmin, ymin, zmin) of the cuboid to encompass the geometry contained within the segment. Returned to user. Passed by reference in all languages.
max – - The upper-most distant diagonal point (xmax, ymax, zmax) of the cuboid to encompass the geometry contained within the segment. Returned to user. Passed by reference in all languages.

Returns

success

bool HC_DCompute_Circumcuboid_By_Key(Key key, DPoint *min, DPoint *max)

Similar to Compute_Circumcuboid_By_Key(), but operates on double-precision data.

See also

HC_Compute_Circumcuboid_By_Key()

Parameters

key – - Key of the segment used for the calculation.
min – - The lower-most nearest diagonal point (xmin, ymin, zmin) of the cuboid to encompass the geometry contained within the segment. Returned to user. Passed by reference in all languages.
max – - The upper-most distant diagonal point (xmax, ymax, zmax) of the cuboid to encompass the geometry contained within the segment. Returned to user. Passed by reference in all languages.

Returns

success

bool HC_DCompute_Circumsphere(char const *segment, DPoint *center, double *radius)

Similar to Compute_Circumsphere(), but operates on double-precision data.

Parameters

segment – - Segment name to use for the calculation.
center – - The center position of a sphere that encompasses the geometry contained within the segment. Returned to user. Passed by reference in all languages.
radius – - The radius length of the encompassing sphere. Returned to user. Passed by reference in all languages.

Returns

success

bool HC_DCompute_Circumsphere_By_Key(Key key, DPoint *center, double *radius)

Similar to Compute_Circumsphere_By_Key(), but operates on double-precision data.

See also

HC_Compute_Circumsphere_By_Key()

Parameters

key – - Key of the segment or geometry to be used for the calculation.
center – - The center position of a sphere that encompasses the geometry contained within the segment. Returned to user. Passed by reference in all languages.
radius – - The radius length of the encompassing sphere. Returned to user. Passed by reference in all languages.

Returns

success

bool HC_Compute_Color(char const *name, char const *out_type, RGB *out_value)

Allows access to the color-conversion routines used internally in HOOPS.

If in_type or out_type are not legitimate an error is signalled. Other errors are not signalled and are returned in the success flag.

DETAILS These routines allow access to the internal color conversion routines used by HOOPS: in the normal processing of Set_Color() and Set_Color_By_Value() . Compute_Color() takes a normal HOOPS color name, such as “pinkish purple” and returns the numeric equivalent in the selected color space. Compute_Color_By_Value() takes a numeric color in one color space and converts it to the equivalent color in another color space.
NOTES: Not all colors that can be represented in the HLS, HSV and HIC color space have an exact equivalent RGB value. For colors that can’t be represented, the nearest legal RGB value is returned instead.

The final RGB values passed to the device usually have a gamma correction applied - these routines do not include gamma correction.

See also

HC_Set_Color, HC_Set_Color_By_Value, HC_Define_Color_Name.

Parameters

name – - A color-by-name color specification, in the style of Set_Color() .
out_type – - Special constant - either “HLS”, “HSV”, “HIC”, or “RGB”. The constant is a quoted string. Uppercase versus lowercase is not significant.
out_value – - A color triple that represents hue, lightness, and saturation, or red, green, and blue, etc., depending on the values of in_type and out_type. Returned to user. Passed by reference in all languages.

Returns

true if it succeeds in turning the input color string into a color value in the format specified by out_type; otherwise, it returns false.

bool HC_Compute_Color_By_Value(char const *in_type, RGB const *in_value, char const *out_type, RGB *out_value)

Similar to Compute_Color(), but operates with a color values rather than names or map indices.

See also

HC_Compute_Color()

Parameters

in_type – - Special constant - either “HLS”, “HSV”, “HIC”, or “RGB”. The constant is a quoted string. Uppercase versus lowercase is not significant.
in_value – - A color triple that represents hue, lightness, and saturation, or red, green, and blue, etc., depending on the values of in_type and out_type. Passed by reference in all languages.
out_type – - Special constant - either “HLS”, “HSV”, “HIC”, or “RGB”. The constant is a quoted string. Uppercase versus lowercase is not significant.
out_value – - A color triple that represents hue, lightness, and saturation, or red, green, and blue, etc., depending on the values of in_type and out_type. Returned to user. Passed by reference in all languages.

Returns

true if the function succeeds in turning the input color string into a color value in the format specified by out_type; otherwise, it returns false.

void HC_Compute_Convex_Hull(int pcount, Point const points[], int *fcount, int face_list[])

Given a set of points, determines the set of faces that minimally bind all the points.

For all but the simplest sets of points there are many possible hulls. However, disregarding degeneracies (coplanar/colinear points), there is only one possible convex hull surrounding any given set of points. Compute_Convex_Hull() computes this shape. The input is a list of points. The output is a face connectivity list suitable for passing to Insert_Shell() .

DETAILS: A “hull”, as used here, is a closed wrapper around a set of points. The hull is a simple polyhedron, its vertices are chosen only from the set of points, and all the points end up either on the surface or within the hull.

Compute_Convex_Hull() only produces convex figures, by definition. However, there is nothing preventing you from artificially moving one of the points inward to form a concave figure after Compute_Convex_Hull() returns. Likewise, Compute_Convex_Hull() only produces closed figures, by definition. There is nothing preventing you from artificially removing one or more of the faces to form an open shell afterwards.

The algorithm used is O(n squared). In other words, it’s going to take a while.

NOTES: The variable, face_list_length, is the number of entries in face_list that the system has used up. face_list_length is returned to you. It is not the total available space you’re passing in. The system assumes your face_list is “big enough” to hold any possible result. Allow for at least 8*pcount*sizeof(int) in face_list - in other words, the new face list contains up to 2*pcount triangles.

Not all the points will necessarily be mentioned in the face_list. Depending on the shape of your object, many points might be completely interior to the hull and thus unconnected.

Another definition of “convex hull” is “the surface of the smallest area that encloses a set of points”.

See also

HC_Compute_Coordinates, HC_Insert_Shell

Parameters

pcount – - Number of valid points in points.
points – - Vector of x-y-z triplets for the coordinates of the vertices. (A simple N*3 can also be used.) Passed by reference always.
fcount – - Total number of integers returned in face_list. Passed by reference always. Returned to user.
face_list – - Encoded description of how to connect the points to build the faces of the hull. Same format as in Insert_Shell() . Passed by reference always. Returned to user. Potentially up to 8*pcount*sizeof(int) in length.

bool HC_Compute_Coordinates(char const *segment, char const *in_system, Point const *in_position, char const *out_system, Point *out_position)

Converts positions back and forth among the various coordinate systems.

The in_system and out_system parameters to Compute_Coordinates() can include one of the following:

DETAILS: This routine examines the attributes present on segment and its owners and allows you to convert from in_system coordinates to out_system coordinates.

local window

The value is in terms of the local window for segment. (The Z coordinate is usually zero.)

outer window

The value is in terms of the outermost window for segment. (“Outermost” refers to the first segment going up from segment, which has a Driver attribute.)

screen range

The value is in window coordinates units based on the value of the screen range in Set_Rendering_Options() set on the segment. If no screen range is set, this is the equivalent to local window.

local pixels

The value is measured in screen pixels within the local window on segment. The upper-left of the window is pixel (0, 0). The pixels go down and to the right. (The Z coordinate is usually zero.)

outer pixels

The value is in terms of pixels within the outermost window on segment.

projection

The value is in projection space (Normalized device coordinates) and maps directly to the window.

viewpoint

A coordinate system based on the position of the observer (camera). The origin is at the camera position. The viewing direction is the Z-axis and the camera up vector is the Y-axis.

world

The value is in normal world coordinates (the coordinate system in which the camera is positioned; the coordinates of geometry after modelling matrices have been applied, but before projecting through a camera into a window.) A window Z value of zero maps to the current camera “target” plane.

camera

The coordinate system used in calls to Set_Camera_Position() . A synonym for world coordinates.

object

The value is in the coordinate system that real geometry lives in. This is similar to “world” coordinates, but does not includes the Modelling Matrices, if any.

If a conversion is ambiguous (one of the matrices is singular), the system will choose arbitrarily among the valid possibilities. If a conversion is impossible (the point is on top of or behind a perspective camera), a false function status will be returned and out_position will be unchanged.

NOTES

Window Z coordinates are described at length under Show_Selection_Position() .

To generate the world coordinates of an eye-ray, given window or pixel coordinates, call this routine twice with two different window or pixel Z coordinates.

If you have many points to transform it is more efficient to call Compute_Transform() to get a transform matrix. Then call Compute_Transformed_Points() to do all the points at once. If you have just one or a couple points to transform, Compute_Coordinates() is more efficient because it doesn’t need to build the matrix.

Calling Compute_XXX() routines to obtain data associated with a display, generates an update. On most devices, this poses no problem. However, for hardcopy devices such as Postscript or CGM, this can generate a blank page. To avoid this problem, applications often open a temporary driver subsegment. The application calls the compute routine, and retains the computed information, and then discards the temporary driver subsegment.

RESTRICTIONS: The Compute_XXX() routines that require information about display drivers, do not work if they are called from an included segment. Display information must be associated with a window to return information about the display.

See also

HC_Compute_Transform, HC_Show_Selection_Position, HC_Show_Polyline, HC_Show_Shell.

Parameters

segment – - The name of a segment that provides the Window, Camera, and/or Driver attributes for the conversion.
in_system – - Special constants for the input and output coordinate spaces. See details.
in_position – - A 3-D coordinate position in the in_system coordinate space. Passed by reference in all languages.
out_system – - Special constants for the input and output coordinate spaces. See details.
out_position – - A 3-D coordinate position in the out_system coordinate space. Passed by reference in all languages. Returned to user.

Returns

success

bool HC_Compute_Coordinates_By_Path(int count, Key const keys[], char const *in_system, Point const *in_position, char const *out_system, Point *out_position)

Similar to Compute_Coordinates(), but concatenates the matrices along a segment path rather than the currently open segment.

See also

HC_Compute_Coordinates()

Parameters

count – - The size of the keys array
keys –
- The array of keys starting with the owning segment and following

long all the way back to the root segment or other desired segment.
in_system – - Special constants for the input and output coordinate spaces.
in_position – - A 3-D coordinate position in the in_system coordinate space. Passed by reference in all languages.
out_system – - Special constants for the input and output coordinate spaces.
out_position – - A 3-D coordinate position in the out_system coordinate space. Passed by reference in all languages. Returned to user.

Returns

success

void HC_Compute_Cross_Product(Vector const *vector1, Vector const *vector2, Vector *out_vector)

Computes the cross product of two vectors.

| i   j   k  |
| x1  y1  z1 |
| x2  y2  z2 |

DETAILS: Compute_Cross_Product() takes two 3-D vectors and computes their vector cross-product.
NOTES: For a bit of linear algebra review, the way to compute a cross product is to calculate the determinant of the following matrix:

Where i, j, and k are the unit vectors along the X, Y, and Z axes, respectively. That works out to be equal to

i*(y1*z2 - z1*y2) - j*(x1*z2 - z1*x2) + k*(x1*y2 - y1*x2)

The result is always perpendicular to both inputs, and of length equal to the length(vector1) * length(vector2) * sin(angle

between vector1 and vector2). The order of the inputs matters. Switching the inputs will reverse the result.

See also

HC_Compute_Coordinates, HC_Compute_Dot_Product

Parameters

vector1 – - input 3D vectors.
vector2 – - input 3D vectors.
out_vector – - output 3D vector returned to the caller. Can point to the same place as vector1 or vector2

void HC_DCompute_Cross_Product(DVector const *vector1, DVector const *vector2, DVector *out_vector)

Similar to Compute_Cross_Product, but operates on double-precision data.

Parameters

vector1 – - input 3D vectors.
vector2 – - input 3D vectors.
out_vector – - output 3D vector returned to the caller. Can point to the same place as vector1 or vector2

double HC_Compute_Dot_Product(Vector const *vector1, Vector const *vector2)

Takes two 3-D vectors and computes their scalar dot-product.

See also

HC_Compute_Coordinates, HC_Compute_Cross_Product

Parameters

vector1 – - Input 3D vector.
vector2 – - Input 3D vector.

Returns

value

double HC_DCompute_Dot_Product(DVector const *vector1, DVector const *vector2)

Similar to Compute_Dot_Product, but operates on double-precision data.

Parameters

vector1 – - Input 3D vector.
vector2 – - Input 3D vector.

Returns

value

void HC_Compute_Identity_Matrix(float out_matrix[])

See also

HC_Set_Modelling_Matrix

DETAILS: Compute_Identity_Matrix() produces a matrix that represents “no transformation”. It can be useful when program logic always assumes a previous transformation exists. The output array is always filled with [1,0,0,0, 0,1,0,0, 0,0,1,0, 0,0,0,1].

Parameters: out_matrix – - Output transformation matrix, returned to the caller.

void HC_DCompute_Identity_Matrix(double out_matrix[])

Similar to Compute_Identity_Matrix(), but operates on double-precision data.

Parameters: out_matrix – - Output transformation matrix, returned to the caller.

void HC_Compute_Matrix_Adjoint(float const matrix[], float out_matrix[])

See also

HC_Compute_Coordinates, HC_Compute_Matrix_Inverse, HC_Compute_Transform, HC_Compute_Transformed_Plane, HC_Set_Modelling_Matrix, HC_Show_Device_Info

DETAILS: Compute_Matrix_Adjoint() takes a general 4x4 transformation and computes its adjoint. The adjoint of a matrix is similar to the inverse of the matrix - the adjoint divided by the determinant gives the inverse. The adjoint is sometimes used in place of the inverse because it’s easier to compute and is never singular.

Parameters

matrix – - Input transformation matrix.
out_matrix – - Output transformation matrix, returned to the caller. Can point to the same place as matrix.

void HC_DCompute_Matrix_Adjoint(double const matrix[], double out_matrix[])

Similar to Compute_Matrix_Adjoint(), but operates on double-precision data.

Parameters

matrix – - Input transformation matrix.
out_matrix – - Output transformation matrix, returned to the caller. Can point to the same place as matrix.

double HC_Compute_Matrix_Determinant(float const matrix[])

See also

HC_Compute_Coordinates, HC_Compute_Matrix_Inverse, HC_Compute_Normalized_Matrix, HC_Compute_Transform, HC_Set_Modelling_Matrix, HC_Show_Device_Info

DETAILS: Compute_Matrix_Determinant() takes a general 4x4 transformation and computes its determinant. If the determinant is zero, the matrix is singular.

Parameters: matrix – - Input transformation matrix.
Returns: value

double HC_DCompute_Matrix_Determinant(double const matrix[])

Similar to Compute_Matrix_Determinant(), but operates on double-precision data.

Parameters: matrix – - Input transformation matrix.
Returns: value

bool HC_Compute_Matrix_Inverse(float const matrix[], float out_matrix[])

If the matrix is singular, Compute_Matrix_Determinant() would return zero. The adjoint (see Compute_Matrix_Adjoint() ) is similar and will always be defined, even for singular matrices. Consider using that instead where applicable.

DETAILS: Compute_Matrix_Inverse() takes a general 4x4 transformation and computes its inverse. If the matrix is singular, the out_matrix will be unchanged and false will be returned.
NOTES

See also

HC_Compute_Coordinates, HC_Compute_Matrix_Determinant, HC_Compute_Matrix_Adjoint, HC_Compute_Transform, HC_Set_Modelling_Matrix, HC_Show_Device_Info

Parameters

matrix – - Input transformation matrix.
out_matrix – - Output transformation matrix, returned to the caller. Can point to the same place as matrix.

Returns

success

bool HC_DCompute_Matrix_Inverse(double const matrix[], double out_matrix[])

Similar to Compute_Matrix_Inverse(), but operates on double-precision data.

Parameters

matrix – - Input transformation matrix.
out_matrix – - Output transformation matrix, returned to the caller. Can point to the same place as matrix.

Returns

success

void HC_Compute_Matrix_Product(float const matrix1[], float const matrix2[], float out_matrix[])

Given:

DETAILS: Compute_Matrix_Product() takes two general 4x4 transformation matrices (from routines such as Compute_Rotation_Matrix() ) and computes their product. For compatibility with Compute_Transformed_Points(), specify the “inner” transformations (e.g., modelling matrices) on the left (as matrix1) and “outer” transformations (e.g., cameras, windows) on the right (as matrix2).

Compute_Matrix_Product(A, B, C);

C = AB

The result is that the following are equivalent:

1) Append_Modelling_Matrix(A);

followed by

Append_Modelling_Matrix(B);

2) Append_Modelling_Matrix(C);

See also

HC_Compute_Coordinates, HC_Compute_Transform, HC_Set_Modelling_Matrix, HC_Show_Device_Info

Parameters

matrix1 – - First input transformation matrix.
matrix2 – - Second input transformation matrix.
out_matrix – - Output transformation matrix, returned to the caller. Can point to the same place as matrix1 or matrix2

void HC_DCompute_Matrix_Product(double const matrix1[], double const matrix2[], double out_matrix[])

Similar to Compute_Matrix_Product(), but operates on double-precision data.

Parameters

matrix1 – - First input transformation matrix.
matrix2 – - Second input transformation matrix.
out_matrix – - Output transformation matrix, returned to the caller. Can point to the same place as matrix1 or matrix2.

void HC_Compute_Minimized_Shell(int in_point_count, Point const in_points[], int in_face_list_length, int const in_face_list[], char const *option_string, int *out_point_count, Point out_points[], int *out_face_list_length, int out_face_list[], int vertex_mapping[], int face_mapping[])

bool HC_Compute_Normalized_Matrix(float const matrix[], float out_matrix[])

If the matrix is singular, Compute_Matrix_Determinant() would return zero.

DETAILS: Compute_Normalized_Matrix() takes a general 4x4 transformation and divides by its determinant. If the input matrix is singular, the out_matrix will be unchanged and false will be returned.
NOTES

See also

HC_Compute_Coordinates, HC_Compute_Matrix_Determinant, HC_Compute_Transform, HC_Set_Modelling_Matrix, HC_Show_Device_Info

Parameters

matrix – - Input transformation matrix.
out_matrix – - Output transformation matrix, returned to the caller. Can point to the same place as matrix.

Returns

success

bool HC_DCompute_Normalized_Matrix(double const matrix[], double out_matrix[])

Similar to Compute_Normalized_Matrix, but operates on double-precision data.

Parameters

matrix – - Input transformation matrix.
out_matrix – - Output transformation matrix, returned to the caller. Can point to the same place as matrix.

Returns

success

bool HC_Compute_Normalized_Vector(Vector const *vector, Vector *out_vector)

See also

HC_Compute_Coordinates, HC_Compute_Transform, HC_Set_Modelling_Matrix, HC_Show_Device_Info

DETAILS: Compute_Normalized_Vector() takes a 3-D vector and divides by its length. If the vector is all zeroes, false will be returned.

Parameters

vector – - Input 3D vector.
out_vector – - Output 3D vector returned to the caller. Can point to the same place as vector .

Returns

success

bool HC_DCompute_Normalized_Vector(DVector const *vector, DVector *out_vector)

Parameters

vector – - Input 3D vector.
out_vector – - Output 3D vector returned to the caller. Can point to the same place as input vector.

Returns

success

void HC_Compute_Offaxis_Rotation(double x, double y, double z, double theta, float out_matrix[])

See also

HC_Compute_Offcenter_Rotation, HC_Set_Modelling_Matrix

DETAILS: Compute_Offaxis_Rotation() produces a matrix that represents a rotation about an arbitrary axis passing through the origin.

Parameters

x – - X coordinate of the vector that specifies the axis of rotation
y – - Y coordinate of the vector that specifies the axis of rotation
z – - Z coordinate of the vector that specifies the axis of rotation
theta – - Angle of rotation.
out_matrix – - Output transformation matrix. Returned to caller.

void HC_DCompute_Offaxis_Rotation(double x, double y, double z, double theta, double out_matrix[])

Similar to Compute_Offaxis_Rotation, but operates on double-precision data.

Parameters

x – - X coordinate of the vector that specifies the axis of rotation
y – - Y coordinate of the vector that specifies the axis of rotation
z – - Z coordinate of the vector that specifies the axis of rotation
theta – - Angle of rotation.
out_matrix – - Output transformation matrix. Returned to caller.

void HC_Compute_Offcenter_Rotation(double alpha, double beta, double theta, double x, double y, double z, float out_matrix[])

See also

HC_Compute_Offaxis_Rotation, HC_Set_Modelling_Matrix

DETAILS: Compute_Offcenter_Rotation() produces a matrix representing a rotation about an arbitrary center of rotation. This essentially consists of a translation of (-x,-y,-z) to the origin. The translation uses a rotation of alpha degrees about the X axis, a rotation of beta degrees about the Y, and a rotation of theta degrees about the Z. Then it does a translation back to (x, y, z).

Parameters

alpha – - Angle of rotation about the X axis.
beta – - Angle of rotation about the Y axis.
theta – - Angle of rotation about the Z axis.
x – - X coordinate of the centroid of rotation
y – - Y coordinate of the centroid of rotation
z – - Z coordinate of the centroid of rotation
out_matrix – - Output transformation matrix, returned to the caller.

void HC_DCompute_Offcenter_Rotation(double alpha, double beta, double theta, double x, double y, double z, double out_matrix[])

Similar to Compute_Offcenter_Rotation, but operates on double-precision data.

Parameters

alpha – - Angle of rotation about the X axis.
beta – - Angle of rotation about the Y axis.
theta – - Angle of rotation about the Z axis.
x – - X coordinate of the centroid of rotation
y – - Y coordinate of the centroid of rotation
z – - Z coordinate of the centroid of rotation
out_matrix – - Output transformation matrix, returned to the caller.

void HC_Compute_Optimized_Shell(int pcount, Point const points[], Vector const normals[], int flist_length, int const face_list[], char const *options, int *new_pcount, Point new_points[], int *new_flist_length, int new_face_list[], int point_mapping_list[], int face_mapping_list[])

Performs one of several computations to prepare shell data for improved rendering performance. The default computation is to remove redundant vertices and degenerate faces.

The HOOPS routine Insert_Shell() accepts a set of points, an encoded description of how to connect the points to form the faces of a shell. Insert_Shell() performs no interrogation of the data received. It has no provision for eliminating redundant points nor for ignoring disconnected points. Compute_Optimized_Shell() accepts data normally used to insert a shell and returns a new set of data with redundancies and discontinuities removed. This new data can then be used to insert a shell. The arrays point_mapping_list and face_mapping_list are available to help you refer to the new data, if given indices to the original data.

DETAILS

../../_images/minshell.gif

Programs designed to work with geometric modelers often receive geometry in a stream. This means they cannot ascertain the overall connectedness of a shell’s faces. For instance, to define a diagonally-split quadrilateral using two faces, one needs only four vertices, with two of them referenced twice. While it is geometrically correct to redefine the “re-used” vertices, for a total of six, face-connectivity information is lost. This is because duplicated points, though equivalent, are still distinct - each face has its “own” vertices. Compute_Optimized_Shell() recaptures the connectivity by eliminating the duplicated vertices and forcing faces to share the remaining unique vertices.

Faces that refer to fewer than three unique vertices are eliminated.

Since shells are arbitrary collections of faces, Compute_Optimized_Shell() can be used to convert a group of polygons into a coherent shell. The advantage is less data must be sent to HOOPS. Performance is improved since fewer points must be transformed and clipped.

Compute_Optimized_Shell() does not allocate memory for you. All arrays passed to it must contain adequate storage.

The following choices are recognized for options:

fix handedness

This option is a convenience for converting a minority of faces to the handedness comprising the majority.

Determines the handedness of the majority of faces, and reverses the winding of the minority faces. Returns facelist data to the caller. Shell data is modified in no other way. Mutually exclusive to options “fix handedness”, “skin”, and “lod”.

This option will also fix the special winding of holes (and nested holes) in shell faces also. A limitation of fixing face handedness is that we cannot do better than the “majority wins” method for the general case.

reverse handedness

This option is a convenience for reversing the winding of shell faces if the option “fix handedness” gives you an inside-out shell and you prefer not to change the appearance with the Heuristic “polygon handedness”.

Reverses the winding of each face in the facelist provided. Returns facelist data to the caller. Shell data is modified in no other way. Mutually exclusive to options “fix handedness”, “skin”, and “lod”.

It should not be necessary to pass in point data.

[no] [level of detail | lod] [ = xx% ]

Causes Compute_Optimized_Shell to abandon the normal redundant-vertices calculation in favor of calculating a Level of Detail (LOD). Any other choice will cause the shell to be reduced using shell simplification instead of the standard code path. The default reduction when LOD is turned on is 50%. If a percentage is specified in the form of xx%, the number of triangles in the model will be reduced to to the given percentage of the original model. The options “skin” and “lod” are mutually exclusive.

The new point count is guaranteed not to be larger than the original, so the original length can be used as upper bounds for allocation. The same goes for the facelist if the input is triangles. If quads (or polygons of higher order) are provided, then the output facelist may be larger. This is because our LOD algorithm outputs triangles only.

With quad input and level of detail = 100%, we will output double the faces. Triangle faces have 4/5 the number of integers that quad faces do, so we don’t need to double the facelist alloc size, rather multiply it by 1.6. This factor shrinks by user-provided level of detail. For example, with quad face input and level of detail = 75%, the new facelist alloc size becomes 1.6*0.75 = 1.2x original.

Generally, for turning n-gon data into a LOD shell with level of detail x, you are safe if you alloc an array of size (Original_FaceList_Length * 4*(n-2)/(n+1) * x).

Alternatively, you can safely run Optimize twice - first just to generate the facelist length (no array passed in), next with the array after your accurately sized alloc. This, however will take more cpu time.

Not set by default.

lod algorithm = [fast | nice]

Use the fast-LOD algorithm, with some visual quality degradation, or the “nice” LOD algorithm, with extra generation time but a better representation. Default is “fast”. Default is “fast”, but only applies if the “lod” option is used.

[no] orphan elimination

If this option is set, points that are not referenced by any face are removed. The default is “orphan elimination”.

[no] skin

Particularly geared towards the needs of the finite element analysis community, this option causes Compute_Optimized_Shell() to abandon its normal goal of merging nearby vertices in favor of extracting the exterior surface from shells that also have interior vertices and faces. This special computation mode works its magic by looking for pairs of faces that reference 3 or more of the same vertex indices. If coincident vertices are not shared for adjacent faces, this computation will not do anything (though running the standard form of Compute_Optimized_Shell() on the data first would solve that problem. The options, “skin” and “lod” are mutually exclusive. When “skin” mode is used only “orphan elimination” has any meaning - the rest are ignored. As usual, the new face list length and new point count are guaranteed not to be larger than the original, so the original lengths can be used as upper bounds for allocation. Not set by default.

[no] tolerance [= nnn oru / nnn % fru]

“Tolerance” controls the identification of duplicate points. If a specification is given in object-relative units (oru), then the points that are separated by a distance less than this value are considered equal.

Often, one cannot ascertain a “good” value for an object-relative tolerance. In this case, specify the tolerance using “feature-relative units (fru)”. Feature size is defined to be the smallest non-zero distance between any two adjacent vertices on any face. It is calculated internally by Compute_Optimized_Shell() , and is constant for the entire collection of faces. The feature-relative tolerance is expressed as a percentage of this minimum distance. A setting less than “tolerance = 100%

fru” guarantees that unequal vertices on a single face won’t be eliminated.

“No tolerance” is the same as “tolerance = 0 oru”.

The default is “no tolerance”.

[no] normal tolerance [= nnn deg / nnn rad / nnn]

“Normal Tolerance” also controls the identification of duplicate points. Points which have an angular difference greater than the specified normal tolerance are assumed to be unique.

“no normal tolerance” is the same as “normal tolerance = 0 deg”.

The default is “no normal tolerance”.

[no] collapsible [= <defined callbackname>]

This option enables the user to replace the default distance measure, euclidian distance, with their own function to determine whether any given two nearby points should be merged or not. While it was originally designed to accept normals as its primary information, any sort of pointer that is passed as normals in the call to Compute_Optimized_Shell will be passed through to the callback.

If you are not interested in the mapping lists, pass a null pointer for either the point_mapping_list or the face_mapping_list. If you are not interested in using normal information as a criterion for collapsing points, pass a null pointer for normals.

NOTES

This function replaces Compute_Minimized_Shell() , which is now obsolete.

It is not legal to pass the same pointer for both input and output.

EXAMPLES

The following example demonstrates passing a struct pointer in place of normals.

typedef struct {
     // contents of this structure are unrestricted
     float   myparam1,  myparam2;
   } optimized_shell_passthru;

// returns 1 if points a and b are collapsible -
   // 0 if points a and b are not collapsible
int are_collapsible_callback (
   void *pts_in,
   void *norms_in,
   int a,
   int b,
   double tolerance_squared,
   double  normal_distance_squared )
  {
       optimized_shell_passthru *info= (optimized_shell_passthru *) norms_in;
       // use info to do any test here, and return the result
  }

  // and this is how the function is called
   optimized_shell_passthru info = { a, b, etc. };
   HC_Define_Callback_Name( "are_collapsible_callback", are_collapsible_callback );
   HC_Compute_Optimized_Shell(
       in_point_count, in_points,
   (void *)(&info),
       in_face_list_length, in_face_list,
       "collapsible = are_collapsible_callback",
       &out_point_count, out_points,
       &out_face_list_length, out_face_list,
       vertex_mapping, face_mapping
   );

The following example demonstrates using the vertex_mapping array to copy attributes from the old shell to the new one. Two things to note from this example:

a) that the check for “vertex_mapping >= 0” really is necessary, since unreferenced vertices from the original shell have vertex_mapping entries set to “-1”; and
b) that performance could be improved if the normals from the original shell were available a priori in an array so that the vertices did not have to be individually opened.
c) vertices in the new shell can potentially be touched more than once.

HC_Show_Shell( old_key, &point_count, points, &face_list_length, face_list );
HC_Compute_Optimized_Shell(
    &point_count, points, NULL,
    &face_list_length, face_list,
    "",
    &new_point_count, new_points,
    &new_face_list_length, new_face_list,
    vertex_mapping, face_mapping
);
new_key = HC_Insert_Shell( new_point_count, new_points, new_face_list_length, new_face_list );
for( i = 0 ; i < point_count ; i++ ) {
    HC_Open_Geometry( old_key );
        HC_Open_Vertex( i );
            HC_Show_Normal( &x, &y, &z );
        HC_Close_Vertex();
    HC_Close_Geometry( );
    if( vertex_mapping[i] >= 0 ) {
        HC_Open_Geometry( new_key );
            HC_Open_Vertex( vertex_mapping[i] );
                HC_Set_Normal( x, y, z );
            HC_Close_Vertex();
        HC_Close_Geometry( );
    }
}

See also

HC_Insert_Shell, HC_Show_Shell, HC_Show_Shell_Size.

Parameters

pcount – - Number of valid points in points.
points – - Vector of x-y-z triplets for the coordinates of the vertices that could be used to build the shell. (A simple N = 3 array can also be used.) Passed by reference always.
normals – - Sequential list of vertex normals, x-y-z triplets. It is legal to pass NULL for this parameter, in which case normal information will be ignored. If non-NULL, however, the normals are assumed to be normalized to length 1. Passed by reference always.
flist_length – - Total number of integers in face_list.
face_list – - Encoded description of how to connect the points to build the faces of the shell. Passed by reference always.
options – - A quoted string or a string variable containing a list of desired options. Passed by reference always.
new_pcount – - Number of valid points in new_points after computation. Returned to caller. Passed by reference always.
new_points – - Vector of x-y-z triplets for the coordinates of the non-redundant vertices that could be used to build the shell. (A simple N = 3 array can also be used.) Returned to caller. Passed by reference always.
new_flist_length – - Total number of integers in computed new_face_list. Returned to caller. Passed by reference always.
new_face_list – - Encoded description of how to connect the points to build the faces of the computed shell. Returned to caller. Passed by reference always.
point_mapping_list – - Mapping of vertices from the original point list to the vertices in the new (computed) point list. In other words, for each old vertex i, point_mapping_list[i] represents the vertex in the new shell to which it has moved. Eliminated points are mapped to -1. Returned to caller. Passed by reference always.
face_mapping_list – - Mapping of faces from the original face list to the new (computed) face list. In other words, for each old face j, face_mapping_list[j] represents the vertex in the new shell to which it has moved. Eliminated faces are mapped to -1. Returned to caller. Passed by reference always.

Key HC_Compute_Capping_Shell(int shell_count, Key const shell_list[], float const plane[])

Creates a shell in the currently open segment that contains an exact copy of the cap geometry that a plane would make when applied to the provided shells.

This function allows developers to access the cap geometry that 3dGS creates when cutting planes are inserted into the scene and capping geometry is turned on. The capping geometry is returned as a single shell and is inserted into the currently open segment. Users must ensure that there is a valid open segment before calling this function.

DETAILS

This function does not apply any modelling transforms to the supplied shells. Users must translate the shells into world space to ensure correct results. Also, the shell provided is a copy of the capping geometry and so the deletion and/or modification of the returned shell will not affect the caps in the scene.

NOTES

This interface currently supports shell generation for cutting planes only. This function must operate on manifold shells. Non-manifold shells will not work.

RESTRICTIONS

See also

HC_Insert_Shell, HC_Insert_Cutting_Plane, HC_Insert_Cutting_Section

Parameters

shell_count – - Number of shells in the shell list array.
shell_list – - List of shells for which the cap(s) will be generated.
plane – - An array of four floats that define the cap plane.

Returns

cap_key - The key to the shell that will contain the capping geometry.

Key HC_Compute_Boolean_Shell(int target_pcount, Point const target_points[], Vector const target_normals[], int target_flist_length, int const target_face_list[], int tool_pcount, Point const tool_points[], Vector const tool_normals[], int tool_flist_length, int const tool_face_list[], char const *options)

Performs one of several boolean operations on two shells. IMPORTANT NOTE: This routine is primarily meant to provide a reasonable visual representation of the boolean result, and has limititions covered in the NOTES section which prevent this routine from being relied on to produce manifold shell results. The routine is provided AS-IS.

This function takes the definitions for two manifold shells and performs one of three boolean operations on those shells. The result is a new shell that gets inserted into the currently open segment. Valid choices for options include the following:

DETAILS

boolean type = [subtract | union | intersect]

Tells 3dGS which specific type of boolean operation to perform on the supplied shells. In the event of a union or an intersection, the order of target and tool does not matter. However, in the case of a subtraction the tool will be subtracted from the target shell.

plane coefficient = [float]

This value is used in the internal logic for determining the boolean result. Changing the value based on the scale of the object can give better results. For both the single and double precision version, the default setting is “plane coefficient = 0.000001”.

plane tolerance = [float]

This value is used in the internal logic for determining the boolean result. Changing the value based on the scale of the object can give better results. The default setting is “plane tolerance = 0.0003” for the single precision version. For the double precision version, the default setting is “plane tolerance = 0.000001”.

plane merge tolerance = [float]

This value is used in the internal logic for determining the boolean result. Changing the value based on the scale of the object can give better results. The default setting is “plane merge tolerance = 0.0003” for the single precision version. For the double precision version, the default setting is “plane merge tolerance = 0.000001”.

target handedness = [left|right]

The polygon handedness of the target shell. If not specified, “left” handedness is assumed.

tool handedness = [left|right]

The polygon handedness of the tool shell. If not specified, “left” handedness is assumed.

This function will perform a Compute_Optimized_Shell() on the resulting boolean shell data before placing it in the currently open segment. The shell will have left polygon handedness. The user may need to delete the tools and target in their scene depending on the intended behavior.

RESTRICTIONS

The two shells that participate in the boolean operation must be closed and manifold bodies. There cannot be overlapping facets or other inconsistencies in the data. You must have consistent handedness in each input shell (though each shell can have it’s own handedness, e.g., the target can have right handedness and the tool can have left handedness) and you must specify the handedness in the options if it differs from the defaults, otherwise one can get unexpected results. The input shells must only contain convex faces.

The faces of the target and tool shells should not be co-planar.

The resulting shell of the Compute_Boolean_Shell() function may contain an excessive number of triangles in the region where the target and tool meet. If the boolean functionality is used for continuous surface removal (for example, recursive use of the boolean operation result as the input value for a subsequent boolean operation), this effect may become exacerbated.

NOTES

Due to the nature of the algorithm, very small triangles may be produced which can lead to precision problems, such as missing faces or faces with wrong handedness. In extreme cases, these precision problems can lead to the creation of extraneous triangles.

See also

HC_Insert_Shell

Parameters

target_pcount – - Number of valid points in targetpoints.
target_points – - Vector of x-y-z triplets for the coordinates of the vertices that could be used to build the target shell. (A simple N = 3 array can also be used) Passed by reference always.
target_normals – - Sequential list of vertex normals of the target shell, x-y-z triplets. It is legal to pass NULL for this parameter, in which case normal information will be ignored. Passed by reference always.
target_flist_length – - Total number of integers in targetface_list
target_face_list – - Encoded description of how to connect the points to build the faces of the target shell. Passed by reference always.
tool_pcount – - Number of valid points in toolpoints.
tool_points – - Vector of x-y-z triplets for the coordinates of the vertices that could be used to build the tool shell. (A simple N = 3 array can also be used) Passed by reference always.
tool_normals – - Sequential list of vertex normals of the tool shell, x-y-z triplets. It is legal to pass NULL for this parameter, in which case normal information will be ignored. Passed by reference always.
tool_flist_length – - Total number of integers in toolface_list.
tool_face_list – - Encoded description of how to connect the points to build the faces of the tool shell. Passed by reference always.
options – - A quoted string or a string variable containing a list of desired options. Passed by reference always.

Returns

key

bool HC_Compute_Polygon_Normal(int count, Point const points[], char const *hand, Vector *out_vector)

See also

HC_Compute_Coordinates, HC_Compute_Polygon_Plane, HC_Compute_Transform, HC_Set_Modelling_Matrix, HC_Show_Polygon, HC_Show_Shell.

DETAILS: Compute_Polygon_Normal() accepts a list of points in the format of Insert_Polygon() and attempts to find a vector that is perpendicular to the polygon. If the points do not all lie in the same plane, the result is indeterminate. If no such vector can be found (the points are all co linear, for example), false is returned and out_vector is unchanged. The polygon must be defined as either “left-handed” (if the fingers of the left hand are curved around the points in the order defined, then the thumb will point in the direction of the normal) or as “right-handed”.

Parameters

count – - Number of xyz triplets in points
points – - As in Insert_Polygon() , xyz triplets to specify the 3D vertices of the polygon. Must be coplanar.
hand – - The definition order of the polygon - “left” or “right”.
out_vector – - Output 3D vector returned to the caller.

Returns

success

bool HC_DCompute_Polygon_Normal(int count, DPoint const points[], char const *hand, DVector *out_vector)

Similar to Compute_Polygon_Normal, but operates on double-precision data.

Parameters

count – - Number of xyz triplets in points
points – - As in Insert_Polygon() , xyz triplets to specify the 3D vertices of the polygon. Must be coplanar.
hand – - The definition order of the polygon - “left” or “right”.
out_vector – - Output 3D vector returned to the caller.

Returns

success

bool HC_Compute_Polygon_Plane(int count, Point const points[], char const *hand, Plane *out_plane)

Compute_Polygon_Plane() is similar to Compute_Polygon_Normal() . The first three values are the polygon normal itself; the addition of the fourth value allows you to write the equation of the plane of the polygon in the form ax + by + cz + d = 0. If no plane can be found, false is returned and out_plane is unchanged.

DETAILS

See also

HC_Compute_Coordinates, HC_Compute_Polygon_Normal, HC_Compute_Transform, HC_Set_Modelling_Matrix, HC_Show_Device_Info, HC_Show_Polygon, HC_Show_Shell.

NOTES: If this function fails, it is often for the same reasons that Compute_Polygon_Normal would as well.

Parameters

count – - Number of xyz triplets in points
points – - As in Insert_Polygon() , xyz triplets to specify the 3D vertices of the polygon. Must be coplanar.
hand – - The definition order of the polygon - “left” or “right”.
out_plane – - Plane equation parameters (a,b,c,d ). Returned to the caller.

Returns

success

bool HC_DCompute_Polygon_Plane(int count, DPoint const points[], char const *hand, DPlane *out_plane)

Similar to Compute_Polygon_Plane, but operates on double-precision data.

Parameters

count – - Number of xyz triplets in points
points – - As in Insert_Polygon() , xyz triplets to specify the 3D vertices of the polygon. Must be coplanar.
hand – - The definition order of the polygon - “left” or “right”.
out_plane – - Plane equation parameters (a,b,c,d ). Returned to the caller.

Returns

success

void HC_Compute_Rotation_Matrix(double alpha, double beta, double theta, float out_matrix[])

See also

HC_Set_Modelling_Matrix

DETAILS: Compute_Rotation_Matrix() produces a matrix representing a rotation about the origin. It consists of a rotation of alpha degrees about the X axis, of beta degrees about Y, and of theta degrees about Z.

Parameters

alpha – - Angle of rotation about the X axis.
beta – - Angle of rotation about the Y axis.
theta – - Angle of rotation about the Z axis.
out_matrix – - Output transformation matrix, returned to the caller.

void HC_DCompute_Rotation_Matrix(double alpha, double beta, double theta, double out_matrix[])

Similar to Compute_Rotation_Matrix(), but operates on double-precision data.

Parameters

alpha – - Angle of rotation about the X axis.
beta – - Angle of rotation about the Y axis.
theta – - Angle of rotation about the Z axis.
out_matrix – - Output transformation matrix, returned to the caller.

void HC_Compute_Scale_Matrix(double x, double y, double z, float out_matrix[])

See also

HC_Compute_Coordinates, HC_Set_Modelling_Matrix, HC_Show_Device_Info

DETAILS: Compute_Scale_Matrix() produces a matrix representing a uniform scaling of the scene. x, y, and z are the scalings along the X, Y, and Z axes. These scale values are commonly positive and identical, but they do not need to be. Note, if any of (x, y, z) are zero, the matrix that results will be singular (non-invertible.)

Parameters

x – - Scale multiplier in the X direction.
y – - Scale multiplier in the Y direction.
z – - Scale multiplier in the Z direction.
out_matrix – - Output transformation matrix, returned to the caller.

void HC_DCompute_Scale_Matrix(double x, double y, double z, double out_matrix[])

Similar to Compute_Scale_Matrix, but operates on double-precision data.

Parameters

x – - Scale multiplier in the X direction.
y – - Scale multiplier in the Y direction.
z – - Scale multiplier in the Z direction.
out_matrix – - Output transformation matrix, returned to the caller.

int HC_Compute_Selection(char const *display, char const *start_seg, char const *action, double x, double y)

Forces the explicit computation and generation of selection events.

Compute_Selection() allows access to the internal routines used for figuring selection events from mouse locations. Given the usual locater information, Compute_Selection() will observe the appropriate attributes and find out what lies at that position. If anything is found, a Selection Event is generated and is made the “current” event. Any previous current event is discarded. The various Show_Selection() routines can then be used to retrieve information about the selection.

DETAILS

If a value for start_seg is given, then testing begins there. Coordinates are measured in terms of that segment’s effective window, and testing is restricted to that window.

The available values for actions are detailed in ::Set_Selectability(). You can also specify conditions for selections with the “conditions” option. For example, if you were viewing a model of a car, you could define a conditional attribute setting called “show_wheels” that makes all wheels in a scene visible, and activate it for only this selection using Compute_Selection(“?Picture”, “.”, “v, conditions = show_wheels”, 0, 0) .

Additionally, you can set Driver Options and Heuristics which pertain to selection. These values will override the settings on the segment for this selection event. Currently this is the selection proximity Driver Option and the selection level, visual selection, detail

selection”, \ref Set_Heuristics_selection_sorting “selection sorting”, \ref Set_Heuristics_related_selection_limit “related selection limit” and \ref Set_Heuristics_internal_selection_limit “internal selection limit” which can be found in

::Set_Heuristics. See the documentation of ::Set_Driver_Options and ::Set_Heuristics for specific details on each of these

options.

Compute_Selection_By_Area() lets you specify a rectangular region of the screen instead of a single point. Every item of

geometry within or overlapping that region is identified and returned as part of the selection event. The “selection proximity”

Driver Option is ignored in the case of testing “by area”, since the geometry must be properly within or overlapping the

specified region. Everything within the area has equal status.

A typical programming sequence that computes a selection and does something with every one of the selected items follows (in

pseudo-C): @code if (Compute_Selection_By_Area (…) > 0) do { Show_Selection_Element (…)

// … process item…

} while (Find_Related_Selection())

\endcode

As with regular selection events, the “related” selections are returned in proximity order. If the proximities are zero (the

position is within the item). The related sections are in front-to-back order. For “by area” selecting, the ordering

is from the approximate center of the area.

Compute_Selection_By_Volume() lets you specify a volume of the screen. The meaning of “screen Z” coordinates is

described in detail under Show_Selection_Position() . Hither must be less than or equal to yon. If

display is given as blank or null, an “object space” test is done, as described below. Similar to

Compute_Selection_By_Area() , Compute_Selection_By_Polylin() lets you specify a polyline. Any object intersected by

the path of the polyline is selected. Selection by polyline will allow users to select things that are outside of the view

frustum, as long as analytic selection is used. The points that define the polyline have their X and Y values defined in window

coordinates. The Z values are ignored.

Compute_Selection_By_Polygon() lets you specify a polygon instead of a polyline. Every item of geometry,

within or overlapping the region defined by the polygon, is identified and returned as part of the selection event. Selecting

using a polygon will select anything that intersects it, even if the geometry is off the screen. The points that define the

polygon have their X and Y values defined in window coordinates. The Z values are ignored.

Compute_Selection_By_Volume() does its selection in “object space”. The idea of an object-space test is to search a certain

volume of space without reference to any screen display. In particular: <ul> <li> Only Compute_Selection_By_Volume() and

Compute_Selection_By_Shell() permit this mode. <li>All input values (left, right, point etc.) must

be in terms of start_seg’s coordinate system - the coordinate system used for defining geometry within

start_seg. <li>Returned values (see Show_Selection_Position() ) will be in that coordinate system. Windowed inner

segments in start_seg are skipped over. <li> Cameras attached to inner segments are warned about (unless they are

skipped because of the “windowed inner segment” rule). <li> The hidden-surface front-to-back ordering is not meaningful. Items

are returned (see Show_Selection() and Find_Related_Selection() ) in the order they are encountered in the database. <li>

Inner modelling matrices are respected. The values returned by Show_Selection_Position() remain in terms of

start_seg’s coordinate system. </li> </ul>

\par NOTES

The status returned by Show_Selection_Source() will be a one if action was “v” or “*”, otherwise zero.

Selectability and visibility are enforced during a Compute_Selection() just as they are during normal user input. An object

must be both visible and selectable to be selected. The “attribute lock” rendering option might be useful for overriding these.

In the current implementation, display, if given, has to be a real driver segment. There are, however, ways to get

around this. Selecting works if the window visibility for display itself is turned off. Alternatively, a debugging

driver - “?driverprintf/null” - can be used for display (the “?driver/null” driver cannot do selection testing.) If

you do use “printf/null”, the “physical size” Driver Option might be useful to get the nominal shape of the screen right.

In the current implementation, if a blank or null start_seg is given to Compute_Selection_By_Area() (so that

window-selecting is turned on), then at most one window selected - the window in effect for the center of the area. Geometry

testing will be limited to that one window.

In the current implementation, the selection-testing code can include a geometry item even if the item is completely covered up

by a polygon closer to the camera. For example - if the item doesn’t know how to tell that the geometry is actually invisible.

(Note the closer polygon will be returned first.) Likewise, once the testing code decides the action is within a

particular window it becomes oblivious to extraneous windows that may overlap some of the geometry.

Compute_Selection() always makes its result the “current” event. To take advantage of having a queue of events, you could use

Queue_Location_Event() to save the information. Then do Compute_Selection() when you see the Location event coming off the

queue.

Compute_Selection_By_Area() typically requires first letting the user rubberband a bounding box into position. The bounding box

is conveniently done in a subsegment that has a viewing camera such as

Set_Camera_By_Volume (“stretched”, -1., 1., -1., 1.)

This makes the geometry coordinate system the same as the window coordinate system. (The “quick moves” Heuristic can also be

useful for rubberbanding.)

Once you have called Compute_Selection(), you can iterate through the list of selected objects via Find_Related_Selection().

Note that the returned selected objects are sorted by z-order for direct hits (objects that were directly under the selection

ray calculated from the position camera and the hit point) followed by objects that were not in the path of the ray but were

within the “selection proximity” of the ray and that these are sorted by their proximity to the ray.

See also

HC_Begin_Shell_Selection, HC_Compute_Coordinates, HC_Find_Related_Selection, HC_Set_Selectability, HC_Set_Visibility, HC_Set_Driver_Options, HC_Show_Selection_Pathname, HC_Set_Heuristics.

RESTRICTIONS: The start_seg parameter must not be an included segment.

Parameters

display – - Commonly “?Picture”. In general, a segment with an attached device driver that knows how to test for selections.
start_seg – - A segment somewhere in the tree belonging to display, at which point it would be good to start selection testing. If blank or null, then testing begins at display.
action – - One of “v”, “^”, “*”, or “O”, as well as “conditions”, i.e., “v, conditions=my_condition”. Action is compared against the Selectability attribute settings as testing proceeds. See details for a discussion on actions.
x – - The nominal mouse x-position, measured in window coordinates: -1.0 to +1.0. If start-seg is non-blank, then the parameter is taken in terms of the window in effect on start-seg, otherwise in terms of display.
y – - The nominal mouse y-position

Returns

count

int HC_Compute_Selection_By_Area(char const *display, char const *start_seg, char const *action, double left, double right, double bottom, double top)

Similar to Compute_Selection(), but operates on a rectangular area.

See also

HC_Compute_Selection()

RESTRICTIONS: The start_seg parameter must not be an included segment.

Parameters

display – - Commonly “?Picture”. In general, a segment with an attached device driver that knows how to test for selections.
start_seg – - A segment somewhere in the tree belonging to display, at which point it would be good to start selection testing. If blank or null, then testing begins at display.
action – - One of “v”, “^”, “*”, or “O”, as well as “conditions”, i.e., “v, conditions=my_condition”. Action is compared against the Selectability attribute settings as testing proceeds. See Set_Selectability() for a detailed explanation of actions.
left – - The -(x) boundary for a rectangular area of the screen, in window coordinates
right – - The (x) boundary for a rectangular area of the screen, in window coordinates
bottom – - The -(y) boundary for a rectangular area of the screen, in window coordinates
top – - The (y) boundary for a rectangular area of the screen, in window coordinates

Returns

count

int HC_Compute_Selection_By_Polygon(char const *display, char const *start_seg, char const *action, int pcount, Point const points[])

Similar to Compute_Selection(), but operates on a polygonal area.

See also

HC_Compute_Selection()

RESTRICTIONS The start_seg parameter must not be an included segment.

Parameters

display – - Commonly “?Picture”. In general, a segment with an attached device driver that knows how to test for selections.
start_seg – - A segment somewhere in the tree belonging to display, at which point it would be good to start selection testing. If blank or null, then testing begins at display.
action – - One of “v”, “^”, “*”, or “O”, as well as “conditions”, i.e., “v, conditions=my_condition”. Action is compared against the Selectability attribute settings as testing proceeds. See Set_Selectability() for a detailed explanation of actions.
pcount – - Number of points contained in the points list.
points – - Set of points that comprise the polyline or polygon used to compute the selection.

Returns

count

int HC_Compute_Selection_By_Polylin(char const *display, char const *start_seg, char const *action, int pcount, Point const points[])

Similar to Compute_Selection(), but operates on polyline intersections.

See also

HC_Compute_Selection()

RESTRICTIONS The start_seg parameter must not be an included segment.

Parameters

display – - Commonly “?Picture”. In general, a segment with an attached device driver that knows how to test for selections.
start_seg – - A segment somewhere in the tree belonging to display, at which point it would be good to start selection testing. If blank or null, then testing begins at display.
action – - One of “v”, “^”, “*”, or “O”, as well as “conditions”, i.e., “v, conditions=my_condition”. Action is compared against the Selectability attribute settings as testing proceeds. See Set_Selectability() for a detailed explanation of actions.
pcount – - Number of points contained in the points list.
points – - Set of points that comprise the polyline or polygon used to compute the selection.

Returns

count

int HC_Compute_Selection_By_Volume(char const *display, char const *start_seg, char const *action, double left, double right, double bottom, double top, double hither, double yon)

Similar to Compute_Selection(), but operates on a cuboid volume.

See also

HC_Compute_Selection()

Parameters

display – - Commonly “?Picture”. In general, a segment with an attached device driver that knows how to test for selections. If blank or null, then an “object space selection” is made.
start_seg – - A segment somewhere in the tree belonging to display, at which point it would be good to start selection testing. If blank or null, then testing begins at display.
action – - One of “v”, “^”, “*”, or “O”, as well as “conditions”, i.e., “v, conditions=my_condition”. Action is compared against the Selectability attribute settings as testing proceeds. See Set_Selectability() for a detailed explanation of actions.
left – - The -(x) boundary for a rectangular area of the screen, in window coordinates
right – - The (x) boundary for a rectangular area of the screen, in window coordinates
bottom – - The -(y) boundary for a rectangular area of the screen, in window coordinates
top – - The (y) boundary for a rectangular area of the screen, in window coordinates
hither – - The -(z) boundary, described in Show_Selection_Position() .
yon – - The (z) boundary, described in Show_Selection_Position() .

Returns

found

void HC_Compute_Text16_From_Text(char const *intext, char const *encoding, int *outcount, unsigned short outtext16[])

Converts from integer-array representations of 16-bit characters to string representations.

See also

HC_Compute_Text_From_Text16()

Parameters

intext – - The characters in packed-byte format.
encoding – - Any of the encoding constants described under Insert_Text() .
outcount – - The number of characters unpacked into outtext16. Passed by reference always. Returned to user.
outtext16 – - The characters in full 16-bit format, one per short element after unpacking. Passed by reference always. Returned to user.

bool HC_Compute_Text_Extent(char const *segment, char const *text, float *xsize, float *ysize)

Finds out what the dimensions are for a given text string.

Unlike most geometry, the size of text depends on a complicated concatenation of attributes, and figuring it out from first principles is not straightforward. Compute_Text_Extent() performs the calculation for you. The returned value for xsize and ysize will be a fraction from 0.0 to 1.0 (or more) of the segment’s window.

DETAILS

Once you have the text extent, it can be used, for example, to build a small bounding box around text that’s being used for string input (to limit the scope of screen updates). Or to lay out a popup menu big enough for the contained text. Or to wrap a highlight line around text.

If you use the text extent numbers to lay out windows, you usually need to multiply xfrac and yfrac by two to convert to a window distance, since windows range from -1 to +1. For example, to build a subwindow at the lower-left of the currently-open segment that’s just big enough to hold a “rabbit”, you might do the following:

Compute_Text_Extent (".", "rabbit", &amp;xfrac, &amp;yfrac)
Open_Segment ("")
    Set_Window (-1., -1. + 2*xfrac, -1., -1. + 2*yfrac)
    Insert_Text (0., 0., 0., "rabbit")
Close_Segment ()

For text with the transforms option enabled via Set_Text_Font(), the xsize and ysize values will be returned in object relative units (oru) instead of the usual screen relative units.

In versions prior to 16.0, the extent returned included a small amount of white space all around. Now, the default behavior for Compute_Text_Extent returns the exact extent for the specified text. To revert to the behavior displayed by Compute_Text_Extent prior to 16.0, you can turn on the legacy text extent option in #Define_System_Options.

NOTES

This compute function does not include descenders or ascenders, such as accents over capitals letters, in the extent calculations.

The device will be “started” if necessary for the Info routines to work. See Show_Font_Info() for details.

Any reference in your program to Compute_Text_Extent_With_Enc() will cause the Kanji font data to be linked. This may increase the size of your executable image.

Compute_Text_Extent_With_Enc() looks odd because it’s been truncated at 31 characters.

The Compute_XXX() routines that require information about display drivers, do not work if they are called from an included segment. This specifically includes Compute_Text_XXX() routines. Display information must be associated with a window to return information about the display.

RESTRICTIONS

Calling Compute_XXX() routines to obtain data associated with a display generates an update. On most devices, this poses no problem. However, for hardcopy devices such as Postscript or CGM, this can generate a blank page. To avoid this problem, applications often open a temporary driver subsegment. The application calls the compute routine, retains the computed information, and then discards the temporary driver subsegment.

See also

HC_PShow_Net_Text_Font, HC_PShow_Net_Text_Path, HC_PShow_Net_Text_Alignment, HC_Show_Device_Info, HC_Show_Font_Info, HC_Show_Text, HC_Show_Text_Encoding, HC_Compute_Coordinates, HC_Compute_Transform

Parameters

segment – - The segment whose attributes (or net attributes) will be applied to the problem.
text – - The text string whose extent is to be tested.
xsize – - The size of the text in the X direction. Returned to the user. Passed by reference always.
ysize – - The size of the text in the Y direction. Returned to user. Passed by reference always.

bool HC_Compute_Text_Extent_By_Key(Key key, float *xfrac, float *yfrac)

Similar to Compute_Text_Extent(), but operates on text referenced by an HC_KEY.

See also

HC_Compute_Text_Extent()

Parameters

key – - Key of the text on which the computation is to be done.
xfrac – - The fraction from 0.0 to 1.0 (or more), in the X direction, of segment’s window that is necessary to hold text. Returned to user. Passed by reference always.
yfrac – - The fraction from 0.0 to 1.0 (or more), in the Y direction, of segment’s window that is necessary to hold text. Returned to user. Passed by reference always.

bool HC_Compute_Text_Extent_By_Path(int count, Key const keys[], char const *text, float *xfrac, float *yfrac)

Similar to Compute_Text_Extent(), but concatenates the matrices along a segment path rather than the currently open segment.

See also

HC_Compute_Text_Extent()

Parameters

count – - The size of the keys array
keys –
- The array of keys starting with the owning segment and following

all the way back to the root segment or other desired segment.
text – - The text string whose extent is to be tested.
xfrac – - The fraction from 0.0 to 1.0 (or more), in the X direction, of segment’s window that is necessary to hold text. Returned to user. Passed by reference always.
yfrac – - The fraction from 0.0 to 1.0 (or more), in the Y direction, of segment’s window that is necessary to hold text. Returned to user. Passed by reference always.

bool HC_Compute_Text_Extent_Enc_Path(int count, Key const keys[], char const *encoding, void const *text, float *xfrac, float *yfrac)

Similar to Compute_Text_Extent_By_Path(), but operates on encoded text rather that Latin1 text.

See also

HC_Compute_Text_Extent()

Parameters

count – - The size of the keys array
keys –
- The array of keys starting with the owning segment and following

all the way back to the root segment or other desired segment.
encoding – - The encoding method used for text.
text – - The text string whose extent is to be tested.
xfrac – - The fraction from 0.0 to 1.0 (or more), in the X direction, of segment’s window that is necessary to hold text. Returned to user. Passed by reference always.
yfrac – - The fraction from 0.0 to 1.0 (or more), in the Y direction, of segment’s window that is necessary to hold text. Returned to user. Passed by reference always.

bool HC_Compute_Text_Extent_With_Enc(char const *segment, char const *encoding, void const *text, float *xfrac, float *yfrac)

Similar to Compute_Text_Extent() but operates on encoded text rather than Latin1 text.

See also

HC_Compute_Text_Extent()

Parameters

segment – - The segment whose attributes (or net attributes) will be applied to the problem.
encoding – - The encoding method used for text.
text – - The text string whose extent is to be tested.
xfrac – - The fraction from 0.0 to 1.0 (or more), in the X direction, of segment’s window that is necessary to hold text. Returned to user. Passed by reference always.
yfrac – - The fraction from 0.0 to 1.0 (or more), in the Y direction, of segment’s window that is necessary to hold text. Returned to user. Passed by reference always.

bool HC_Compute_Text_Metrics(int count, Key const *keys, char const *encoding, void const *text, char const *options, int *size, float values[])

bool HC_Compute_Text_Metrics_Size(int count, Key const *keys, char const *encoding, void const *text, char const *options, int *size)

void HC_Compute_Text_From_Text16(int incount, unsigned short const intext16[], char const *encoding, char *outtext)

Converts from string to integer-array representations of 16-bit characters.

HOOPS routines such as Insert_Text_With_Encoding() and Show_String_With_Encoding() expect their input and output to be in a “packed byte” format described under Insert_Text() . It’s more convenient, however, for your program to do its text work with the text packed exactly one character per 16-bit word. Compute_Text_From_Text16() and Compute_Text16_From_Text() make this conversion for you.

DETAILS

The Compute_XXX() routines that require information about display drivers, do not work if they are called from an included segment. Display information must be associated with a window to return information about the display.

RESTRICTIONS

Calling Compute_XXX() routines to obtain data associated with a display generates an update. On most devices, this poses no problem. However, for hardcopy devices such as Postscript or CGM, this can generate a blank page. To avoid this problem, applications often open a temporary driver subsegment, call the compute routine, retain the computed information, and then discard the temporary driver subsegment.

See also

HC_Insert_Text, HC_Edit_Text, HC_Show_Text, HC_Show_Text_Encoding, HC_Get_String, HC_Show_String.

Parameters

incount – - Number of characters in intext16.
intext16 – - An array of 16-bit integers. Each integer represents one short character.
encoding – - Any of the encoding constants described under Insert_Text() .
outtext – - The characters from “intext16”, in packed byte format. Passed by reference always. Returned to user.

void HC_Compute_Text_Outline(char const *segment, char const *text, int *pcount, Point points[], int *flist_length, int face_list[])

Calculates a polyhedral representation of the given text glyphs.

Often, setting the path or alignment of text isn’t enough to acheive certain effects. For example, one might want to “warp” text characters or render them under the influence of light sources or a texture map. In these instances, normal Hoops text is not flexible enough, but other Hoops geometries are. Compute_Text_Outline() is the gateway between text characters and their geometric representations.

DETAILS

The output of these routines is exactly like Show_Shell() and its variants. The data collected from Compute_Text_Outline() can be passed directly to Insert_Shell() . Shells can be subjected to a wide range of transformations and renderings.

You can use Compute_Text_Outline_Size() to determine how large the points and face_list arrays are going to need to be, before you actually call Compute_Text_Outline() .

The text attributes in effect within the segment are taken into account when generating the outline, obeying the typeface selection, size, etc.

The points that are returned will all lie in the z=0 plane, and will be scaled down by the text size so that the glyphs will nominally be of unit height, with protruding ascenders and descenders. Even if the text has already been inserted at some position in a segment, the resulting points will be returned with (0,0,0) as the first character’s origin. Since the geometric representation has the same physical dimensions, no matter which text size is chosen, text size may be used to control the resolution of the generated outline. Increasing the text size gives you more points, not a larger figure.

See also

HC_Insert_Text, HC_Show_Font_Info, HC_PShow_Net_Text_Font, HC_PShow_Net_Text_Path, HC_PShow_Net_Text_Alignment, HC_Show_Device_Info, HC_Show_Font_Info, HC_Show_Text, HC_Show_Text_Encoding, HC_Compute_Coordinates, HC_Compute_Text_Extent, HC_Compute_Transform

NOTES: Some of the routine names look odd because they’ve been truncated at 31 characters.
RESTRICTIONS: Not all text fonts have outline representations. If you request an outline from a text font and one cannot be generated, a warning message is issued. You should use Show_Font_Info() to determine if a font is “outlineable”.

Parameters

segment – - The segment whose attributes (or net attributes) will be applied to the problem.
text – - The text string whose outline is to be computed.
pcount – - Number of valid points in points. Returned to caller. Passed by reference always.
points – - Vector of x-y-z triplets for the coordinates of the vertices to be used to build the outline. (A simple N x 3 array may also be used.) Returned to caller. Passed by reference always.
flist_length – - Total number of integers in face_list. Returned to caller. Passed by reference always.
face_list – - Encoded description of how to connect the points to build the faces of the outline. Returned to caller. Passed by reference always.

void HC_Compute_Text_Outline_By_Key(Key key, int *pcount, Point points[], int *flist_length, int face_list[])

Similar to Compute_Text_Outline(), but operates on an object referenced by an HC_KEY.

See also

HC_Compute_Text_Outline()

Parameters

key – - The numeric identifier returned by a previous call to Insert_Text() or Insert_Text_With_Encoding() .
pcount – - Number of valid points in points. Returned to caller. Passed by reference always.
points – - Vector of x-y-z triplets for the coordinates of the vertices to be used to build the outline. (A simple N x 3 array may also be used.) Returned to caller. Passed by reference always.
flist_length – - Total number of integers in face_list. Returned to caller. Passed by reference always.
face_list – - Encoded description of how to connect the points to build the faces of the outline. Returned to caller. Passed by reference always.

void HC_Compute_Text_Outline_Size(char const *segment, char const *text, int *pcount, int *flist_length)

Finds out the size of the text outline. This is useful for determining the size of the points array needed to store incoming data from Compute_Text_Outline().

See also

HC_Compute_Text_Outline()

Parameters

segment – - The segment whose attributes (or net attributes) will be applied to the problem.
text – - The text string whose outline is to be computed.
pcount – - Number of valid points in points. Returned to caller. Passed by reference always.
flist_length – - Total number of integers in face_list. Returned to caller. Passed by reference always.

void HC_Compute_Text_Outline_Size_By(Key key, int *pcount, int *flist_length)

Similar to Compute_Text_Outline_Size(), but enables the user to pass in a key for the desired text object.

See also

HC_Compute_Text_Outline()

Parameters

key – - The numeric identifier returned by a previous call to Insert_Text() or Insert_Text_With_Encoding() .
pcount – - Number of valid points in points. Returned to caller. Passed by reference always.
flist_length – - Total number of integers in face_list. Returned to caller. Passed by reference always.

void HC_Compute_Text_Outline_Size_Wi(char const *segment, char const *encoding, void const *etext, int *pcount, int *flist_length)

Similar to Compute_Text_Outline_Size(), but operates on encoded text rather than Latin1 text.

See also

HC_Compute_Text_Outline()

Parameters

segment – - The segment whose attributes (or net attributes) will be applied to the problem.
encoding – - The encoding method used for text.
etext – - Same as text, but encoded as in Insert_Text_With_Encoding() .
pcount – - Number of valid points in points. Returned to caller. Passed by reference always.
flist_length – - Total number of integers in face_list. Returned to caller. Passed by reference always.

void HC_Compute_Text_Outline_With_En(char const *segment, char const *encoding, void const *etext, int *pcount, Point points[], int *flist_length, int face_list[])

Similar to Compute_Text_Outline(), but operates on encoded text rather than Latin1 text.

See also

HC_Compute_Text_Outline()

Parameters

segment – - The segment whose attributes (or net attributes) will be applied to the problem.
encoding – - The encoding method used for text.
etext – - Same as text, but encoded as in Insert_Text_With_Encoding() .
pcount – - Number of valid points in points. Returned to caller. Passed by reference always.
points – - Vector of x-y-z triplets for the coordinates of the vertices to be used to build the outline. (A simple N x 3 array may also be used.) Returned to caller. Passed by reference always.
flist_length – - Total number of integers in face_list. Returned to caller. Passed by reference always.
face_list – - Encoded description of how to connect the points to build the faces of the outline. Returned to caller. Passed by reference always.

void HC_Compute_Text_Outline_By_Path(int count, Key const keys[], char const *text, int *pcount, Point points[], int *flist_length, int face_list[])

Similar to Compute_Text_Outline(), but concatenates the matrices along a segment path rather than the specified segment.

See also

HC_Compute_Text_Outline().

Parameters

count – - The size of the keys array
keys – - The array of keys starting with the text key (or effective owning segment if a text string is explicitly specified) and following all the way back to the root segment or other desired segment.
text – - The text string whose outline is to be computed. ignored if first key in path is a text key.
pcount – - Number of valid points in points. Returned to caller. Passed by reference always.
points – - Vector of x-y-z triplets for the coordinates of the vertices to be used to build the outline. (A simple N x 3 array may also be used.) Returned to caller. Passed by reference always.
flist_length – - Total number of integers in face_list. Returned to caller. Passed by reference always.
face_list – - Encoded description of how to connect the points to build the faces of the outline. Returned to caller. Passed by reference always.

void HC_Compute_Text_Outline_Size_Pa(int count, Key const keys[], char const *text, int *pcount, int *flist_length)

Similar to Compute_Text_Outline(), but concatenates the matrices along a segment path rather than the specified segment.

See also

HC_Compute_Text_Outline().

Parameters

count – - The size of the keys array
keys – - The array of keys starting with the text key (or effective owning segment if a text string is explicitly specified) and following all the way back to the root segment or other desired segment.
text – - The text string whose outline is to be computed. ignored if first key in path is a text key.
pcount – - Number of valid points in points. Returned to caller. Passed by reference always.
flist_length – - Total number of integers in face_list. Returned to caller. Passed by reference always.

bool HC_Compute_Transform(char const *segment, char const *in_system, char const *out_system, float matrix[])

Converts positions back and forth among the various coordinate systems.

This routine examines the attributes present on segment and its owners, returns a matrix suitable for converting points or planes from in_system coordinates to out_system coordinates. The matrix will often be passed directly to Compute_Transformed_Points() or Compute_Transformed_Plane() .

DETAILS

If you have just one or a couple of points to transform it might be more efficient to call Compute_Coordinates() , the sister routine of Compute_Transform() . Also, if you are going to call Compute_Transformed_Plane() for a number of planes, check the note on efficiency at the bottom of Compute_(Vectors_and_Matrices).

The in_system and out_system parameters to Compute_Coordinates() is a comma-separated list of options which can include the following:

local window

The value is in terms of the local window for segment. (The Z coordinate is usually zero.)

outer window

The value is in terms of the outermost window for segment. (“Outermost” refers to the first segment going up from segment which has a Driver attribute.)

local pixels

The value is measured in screen pixels within the local window on segment. The upper-left of the window is pixel (0, 0); they descend going down and to the right. (The Z coordinate is usually zero.)

outer pixels

The value is in terms of pixels within the outermost window on segment.

viewpoint

The value is in viewpoint coordinate system, which is based on the position of the observer (camera). The origin is at the camera position. The viewing direction is the Z axis and the camera up vector is the Y axis.

world

The value is in normal world coordinates (the coordinate system in which the camera is positioned; the coordinates of geometry after modelling matrices have been applied, but before projecting through a camera into a window.) A window Z value of zero maps to the current camera “target” plane.

camera

The coordinate system used in calls to Set_Camera_Position() , etc. A synonym for world coordinates.

object

The value is in the coordinate system that real geometry lives in (such as “world” coordinates, but does not include the Modelling Matrices, if any).

If a conversion is ambiguous (one of the matrices is singular), the system chooses arbitrarily among the valid possibilities. If a conversion is impossible (e.g., the camera is singular), a false function status returns and matrix will be unchanged.

If your transform doesn’t include a perspective transform - if it doesn’t include going from world or camera space to a perspective window space - the fourth column of the returned matrix is guaranteed to be zero-zero-zero-one.

NOTES

If the fourth column of a matrix is not zero-zero-zero-nonzero, that matrix can’t be used in a call to Set or Append Modelling Matrix.

If the in_system specification matches the out_system specification, the routine immediately returns true with an identity matrix. In the interest of speed, no error checking is conducted.

Calling Compute_XXX() routines to obtain data associated with a display generates an update. On most devices, this poses no problem. However, for hardcopy devices such as Postscript or CGM, this can generate a blank page. To avoid this problem, applications often open a temporary driver subsegment, call the compute routine, retain the computed information, and then discard the temporary driver subsegment.

RESTRICTIONS: The Compute_XXX() routines that require information about display drivers, do not work if they are called from an included segment. Display information must be associated with a window to return information about the display.

See also

HC_Compute_Coordinates, HC_Show_Selection_Position, HC_Show_Polyline, HC_Show_Shell, HC_Show_Marker.

Parameters

segment – - The name of a segment that provides the Window, Camera, and/or Driver attributes for the conversion.
in_system – - Special constants for the input and output coordinate spaces.
out_system – - Special constants for the input and output coordinate spaces.
matrix – - The transformation matrix necessary to take points from in_system to out_system. Passed by reference in all languages. May need to be transposed in languages other than C (unless immediately passed back into Visualize.) Returned to user.

Returns

success

bool HC_DCompute_Transform(char const *segment, char const *in_system, char const *out_system, double matrix[])

Similar to Compute_Transform(), but operates on double-precision data.

Parameters

segment – - The name of a segment that provides the Window, Camera, and/or Driver attributes for the conversion.
in_system – - Special constants for the input and output coordinate spaces.
out_system – - Special constants for the input and output coordinate spaces.
matrix – - The transformation matrix necessary to take points from in_system to out_system. Passed by reference in all languages. May need to be transposed in languages other than C (unless immediately passed back into Visualize.) Returned to user.

Returns

success

bool HC_Compute_Transform_By_Path(int count, Key const keys[], char const *in_system, char const *out_system, float matrix[])

Similar to Compute_Transform(), but concatenates the matrices along a segment path rather than the currently open segment.

See also

HC_Compute_Transform()

Parameters

count – - The size of the keys array
keys – - The array of keys starting with the owning segment and following all the way back to the root segment or other desired segment.
in_system – - Special constants for the input and output coordinate spaces.
out_system – - Special constants for the input and output coordinate spaces.
matrix –
- The transformation matrix necessary to take points from in_system to out_system. Passed by reference in all languages. May need to be transposed in languages other than C (unless immediately passed back into HOOPS.) Returned to user.

Returns

success

bool HC_DCompute_Transform_By_Path(int count, Key const keys[], char const *in_system, char const *out_system, double matrix[])

Similar to Compute_Transform_By_Path(), but operates on double-precision data.

See also

HC_Compute_Transform_By_Path()

Parameters

count – - The size of the keys array
keys – - The array of keys starting with the owning segment and following all the way back to the root segment or other desired segment.
in_system – - Special constants for the input and output coordinate spaces.
out_system – - Special constants for the input and output coordinate spaces.
matrix – - The transformation matrix necessary to take points from in_system to out_system. Passed by reference in all languages. May need to be transposed in languages other than C (unless immediately passed back into HOOPS.) Returned to user.

Returns

success

bool HC_Compute_Transformed_Plane(Plane const *plane, float const matrix[], Plane *out_plane)

Applies a user-defined transform to a single plane.

Since by nature a plane transform involves a (expensive) matrix adjoint calculation, it is important for performance reasons to use the Compute_Transformed_Planes() variant whenever you have a large number of planes that need to be transformed by the same matrix.

DETAILS: Compute_Transformed_Plane() accepts a general 4x4 matrix, inverts it, multiplies it on the right by the plane equation, and normalizes the result. This action produces a new plane equation. The first three values of the transformed plane represent the transformed normal vector. If the matrix or the transformed plane is singular, false is returned and out_plane is unchanged. If you have many planes to convert it might be more efficient to invert the matrix (or, better, to find the adjoint) once, then multiply the planes through it by hand.
NOTES

See also

HC_Compute_Coordinates, HC_Compute_Polygon_Plane, HC_Compute_Transform, HC_Set_Modelling_Matrix, HC_Show_Device_Info, HC_Show_Geometry_Pointer, HC_Show_Polygon, HC_Show_Shell.

Parameters

plane – - Input plane equation parameters (a,b,c,d).
matrix – - Input transformation matrix.
out_plane – - Plane equation parameters (a,b,c,d ). Returned to caller. Can point to the same place as plane.

Returns

True if the calculation was a success

bool HC_DCompute_Transformed_Plane(DPlane const *plane, double const matrix[], DPlane *out_plane)

Similar to Compute_Transformed_Plane(), but operates on double-precision data.

Parameters

plane – - Input plane equation parameters (a, b, c, d).
matrix – - Input transformation matrix.
out_plane – - Plane equation parameters (a, b, c, d). Returned to caller. Can point to the same place as plane.

Returns

True if the calculation was a success

bool HC_Compute_Transformed_Planes(int count, Plane const planes[], float const matrix[], Plane out_planes[])

Applies a user-defined transform to a group of planes.

See also

HC_Compute_Transformed_Plane()

Parameters

count – - Number of plane equations in planes
planes – - A 4 x count array of plane equation parameters (a, b, c, d).
matrix – - Input transformation matrix.
out_planes – - Plane equation parameters (a, b, c, d). Returned to planes the caller. Can point to the same place as plane.

Returns

True if the calculation was a success

bool HC_DCompute_Transformed_Planes(int count, DPlane const planes[], double const matrix[], DPlane out_planes[])

Applies a user-defined transform to a group of planes.

See also

HC_Compute_Transformed_Plane()

Parameters

count – - Number of plane equations in planes
planes – - A 4 x count array of plane equation parameters (a,b,c,d).
matrix – - Input transformation matrix.
out_planes – - Plane equation parameters (a, b, c, d). Returned to planes the caller. Can point to the same place as plane.

Returns

True if the calculation was a success

void HC_Compute_Transformed_Points(int count, Point const points[], float const matrix[], Point out_points[])

Applies a user-specified transform to any number of points.

See also

HC_Compute_Coordinates, HC_Compute_Transform, HC_Set_Modelling_Matrix, HC_Show_Device_Info, HC_Show_Polyline, HC_Show_Shell, HC_Show_Marker.

Parameters

count – - Number of xyz triplets in points
points – - As in Insert_Polygon() , xyz triplets to specify the 3D vertices of the polygon.
matrix – - Input transformation matrix.
out_points – - Output points: points put through matrix. Can point to the same place as points.

void HC_Compute_Translation_Matrix(double x, double y, double z, float out_matrix[])

See also

HC_Compute_Coordinates, HC_Set_Modelling_Matrix, HC_Show_Device_Info

Parameters

x – - Translation in the X direction.
y – - Translation in the Y direction.
z – - Translation in the Z direction.
out_matrix – - Output transformation matrix, returned to the caller.

void HC_DCompute_Translation_Matrix(double x, double y, double z, double out_matrix[])

Similar to Compute_Translation_Matrix(), but operates on double-precision data.

Parameters

x – - Translation in the X direction.
y – - Translation in the Y direction.
z – - Translation in the Z direction.
out_matrix – - Output transformation matrix, returned to the caller.

double HC_Compute_Vector_Length(Vector const *vector)

See also

HC_Compute_Coordinates, HC_Compute_Cross_Product, HC_Compute_Dot_Product

Parameters: vector – - Input 3D vector.
Returns: value - the scalar length of a vector

double HC_DCompute_Vector_Length(DVector const *vector)

Similar to Compute_Vector_Length(), but operates on double-precision data.

Parameters: vector – - Input 3D vector.
Returns: value - the scalar length of a vector

void HC_Control_Update(char const *segment, char const *options)

Controls the amount of redrawing for the subsequent update.

Normally, when you make a change to the HOOPS tree (by deleting geometry, moving objects, etc.) HOOPS marks the modified segments as requiring a redraw. At the next Update_Display() or equivalent call, HOOPS traverses the list of segments requiring redraws. Then HOOPS either overlays the changes on top of the existing scene (Incremental Updates), or erases and redraws the windows in which changes were made (in cases where incremental updates are not legal). The end result is that after the Update_Display() call, the picture on the screen matches the picture described by the HOOPS tree. “Update Interrupts” allow an update to be interrupted and later modified. For example, the user could change the camera angle half way through an update. But eventually HOOPS will start redrawing the scene again until it arrives at a picture matching the most recent database.

Supported Options:: bounding volume retention, clear interesting, compile only, compute bounding volume, mark interesting, redraw everything, redraw geometry, redraw partial erase, refresh, set created, set cut geometry regeneration, set derived geometry regeneration, set hidden line regeneration, set shadow regeneration, set static model regeneration, unset redraw
DETAILS

Sometimes you might not want the screen to exactly match the HOOPS tree in order to reduce screen redrawing. For instance, when performing a complex hidden surfaced drawing the user might want to abort the update altogether (leading to an incorrect, half drawn picture). The user might want to work with the half-drawn image, then later force a full update.

Control_Update() allows an application to control the amount of redrawing that HOOPS undertakes on the next update (by setting or clearing internal segment and geometry flags). The options parameter to Control_Update() can include a comma-separated list of the following:

[no] bounding volume retention | [no] bounding retention

Requests that HOOPS keep bounding volume from update to update. This is the default. There might be circumstances where the bounding volume is only appropriate for a single update, in which case there is no need to retain it.

clear interesting

Clears the “interesting bit” for the specified segment or geometry. This is only of use to HOOPS I.M. users.

compile only

When static model is enabled, an update is actually a two step process, broadly speaking:

Step 1: If necessary, generate the static model.

Step 2: Draw using the static model information.

The “compile only” option requests that HOOPS only perform step 1, which is the static model generation portion of an update. No actual drawing will occur. Whether or not it is “necessary” to generate the static model is somewhat complicated. The static model data must be missing, or out of date, AND this must be the second update since the last change (this is to prevent thrashing, if the scene is changing - in other words, not static).

Static model generation is an expensive operation. You should avoid doing it unless you have to. But in those cases when you know it must be done, you might want to choose when it is done so you can minimize or mask the performance hit. Breaking up the steps of an expensive update could help do that.

We recommend that you use this option only if you have display lists set to segment and/or static model enabled. This option is mainly used for debugging and in most cases you wouldn’t need to use it.

This option is only available for DX11 and OpenGL2.

compute bounding volume[s]

Requests that HOOPS current bounding volume be recalculated. This is useful when geometry has been deleted or moved. By default, bounding volumes are kept up to date with the database. However, the volumes increase in size only as necessary. This option can be used to recompute the bounding volume independent of an increase or decrease in size.

mark interesting

Sets the “interesting bit” for the specified segment or geometry. This is only of use to HOOPS I.M. users.

redraw everything | redraw geometry | redraw partial erase

These options tell HOOPS to flag a segment or a primitive so it will be drawn during the next update. It makes sense to use only one of these options, where each option describes how the redraw will occur.

“Redraw everything” indicates that for each segment and primitive specified, the entire containing window should be erased and completely redrawn (a full scene refresh).

“Redraw geometry” indicates that the specified segments or primitives need to be drawn, but the rest of the scene can be left alone, if possible. (No window clear, just the specified geometry redraws).

“Redraw partial erase” is the same as “redraw geometry” but uses partial erase methods where possible. You must also use Set_Heuristics (‘partial erase’) for this to take effect.

refresh

This option tells HOOPS to pull the back buffer onto the screen. This is a useful way to update the screen after an expose event like when a window that was occluding your scene is moved away.

set created

Treats the segment as if the contents had just been inserted after the previous update.

set cut geometry regeneration | unset cut geometry regeneration

Forces 3dGS to ignore it’s internal update flags and either completely regenerate or leave the cutting geometry as it currently is.

set derived geometry regeneration | unset derived geometry regeneration

Forces 3dGS to ignore it’s internal update flags and either completely regenerate or leave the derived geometry as it currently is. Derived geometry consists of shadows and cut geometry.

set hidden line regeneration | unset hidden line regeneration

Forces HOOPS to ignore its internal update flags, and either completely regenerate or leave the hidden line geometry as is. This option only applies when the hidden surface removal

algorithm” is set to “hidden line”.

@anchor Control_Update_set_shadow_regeneration

set shadow regeneration | unset shadow regeneration

Forces 3dGS to ignore it’s internal update flags and either completely regenerate or leave the shadow as it currently is.

Derived geometry consists of shadows and cut geometry.

@anchor Control_Update_set_static_model_regeneration

set static model regeneration | unset static model regeneration

Forces 3dGS to regenerate the internal static model or leave it as is during the next call to Update_Display().

@anchor Control_Update_unset_redraw

unset redraw

Clears the redraw bits for the specified segments informing HOOPS that nothing needs to be redrawn.

\par NOTES

When using these routines, the application is taking major responsibility for the resulting picture, and how it is drawn. Use

of these functions can easily lead to code that is hard to understand and maintain. These functions should be used sparingly,

or not at all.

To take full control (and responsibility) of HOOPS redraw traversal, specify “no update control” with the Define_System_Options() routine.

Areas can be ignored when they are not meaningful for a given set of options.

Control_Update() replaces and extends the functionality of the Mark_As_Updated() and Mark_As_Refresh_Needed() routines.

See also

HC_Define_System_Options, HC_Update_Display.

Parameters

segment – - Segment(s) to be controlled. Can contain wildcards.
options – - Specification of the level of update desired.

void HC_Control_Update_Area(char const *segment, double left, double right, double bottom, double top, char const *options)

Similar to Control_Update(), but operates on the objects within a defined window area.

See also

HC_Control_Update()

Parameters

segment – - Segment(s) to be controlled. Can contain wildcards.
left – - Window coordinates, (e.g. -1.0, 1.0, -1.0, 1.0) of the area
right – -
bottom – -
top – -
options – - Specification of the level of update desired.

void HC_Control_Update_Area_By_Key(Key key, double left, double right, double bottom, double top, char const *options)

Similar to Control_Update_Area(), but operates on an object referenced by an HC_KEY.

See also

HC_Control_Update()

Parameters

key – - Key of the segment or geometry to be controlled.
left – - Window coordinates, (e.g. -1.0, 1.0, -1.0, 1.0) of the area
right – -
bottom – -
top – -
options – - Specification of the level of update desired.

void HC_Control_Update_By_Key(Key key, char const *options)

Similar to Control_Update(), but operates on an object referenced by an HC_KEY.

See also

HC_Control_Update()

Parameters

key – - Key of the segment or geometry to be controlled.
options – - Specification of the level of update desired.

bool HC_Convert_Precision(Key key, char const *options)

This function is used to convert an entity to either single or double-precision. Use the options string to specify what data type you want. If key is a segment key, you must also specify which attribute you are interested in.

DETAILS

To convert to single-precision, the options string should be “single”. For double-precision, it should be “double”. If you are converting double data to single-precision data, this can be a lossy procedure as some data will necessarily be discarded. To ensure the function produces an acceptable result, you may also choose from two suboptions, “precision”, and “range”. To ensure the exponent part of a double-precision value will fit into a single-precision value, use the suboption “range”. To ensure no significant bits are discarded from the mantissa during the conversion, use the suboption “precision”. For example,

// converts to single-precision only if the mantissa is not truncated
HC_Convert_Precision(myGeometryKey, "single=(precision)");

// converts to single-precision only if the exponent fits in a single-precision value
HC_Convert_Precision(myGeometryKey, "single=(range)");

// converts to single-precision only if both the mantissa and exponent remain intact
HC_Convert_Precision(myGeometryKey, "single=(precision, range)");

// converts to single-precision, but does not do any safety checking. data may be discarded.
HC_Convert_Precision(myGeometryKey, "single");

If key is a segment key, prepend the attribute to the options string. Valid options are “camera”, “modelling matrix”, “clip region”, and “bounding”. For example, to convert the camera to a double-precision camera:

HC_Convert_Precision(mySegmentKey, "camera, double");

See also

HC_Check_Double_Precision

Parameters

key – - the key that will be converted to either single or double-precision
options – - the options string, only used if ‘key’ is a segment key (see details, below)

Returns

true if the conversion succeeded, false otherwise

void HC_Define_Alias(char const *name, char const *expansion)

Permits a “shorthand” name to be used in place of a longer proper name of a segment.

The expansion of an alias can include wildcard characters, references to other names, or anything you want. The expansion is substituted literally when the alias is encountered and execution continues. At definition time, the expansion is simply recorded.

DETAILS: Sometimes full segment tree names will get too lengthy to carry around. Sometimes a utility package would like to define or refer to a fixed special segment name (for example, “?Active Window”). Or sometimes you might want to hide unnecessary details (such as a special name required for the current hardcopy device) from the higher levels of your program. In such cases, Define_Alias() allows you to establish substitutions to be made. All aliases begin with a “?”, and all names that begin with a “?” in a segment specification must be in the system’s list of aliases.

The defined name must include the leading “?”.

See also

HC_Open_Segment, HC_Flush_Contents, HC_Include_Segment, HC_Style_Segment, HC_Define_Color_Name.

NOTES: A warning is given for redefining an already existing name.
RESTRICTIONS

Parameters

name – - Simple name to be added to the list of definitions.
expansion – - The literal and precise string of characters that should be substituted for name.

void HC_Define_Callback_Name(char const *name, Void_Routine callback)

Defines a unique name as a legal callback.

Define_Callback_Name is part of the classic HOOPS Intermediate Mode (I.M.) system. The name is defined in the system as a legal callback and can be used in subsequent calls to Set_Callback() . The name you choose is up to you.

DETAILS

Defining names before using them makes programs more readable. Defining names also allows the system to correctly read and write callback routines to a metafile.

NOTES

A warning is given for redefining an existing name.

The limit on the length of callback names is large (on the order of 216 characters.)

Parameters

name – - Name of new callback routine to be added to the system’s list.
callback – - Address of new callback routine, a routine returning nothing.

void HC_Define_Color_Name(char const *name, char const *er_name, char const *ish_name, char const *definition)

Adds a new color name (for example, “VERMILION”) to the existing colors in the system’s tables (for example, “RED”).

The new name, er_name, ish_name are defined in the system as legal colors, and can be used anywhere built-in color name can be used. The choice of which name to define as what is up to you. If you define “purplish” as a variation of “army green”, and “army green” as a synonym for “yellow”, the system responds “of course”. The syntax rules are liberal. The names can be as simple or as flowery as you please. Lastly, if you need several variations on a name, it is legal to list them all at once. For example

DETAILS

Define_Color_Name(“aqua, my favorite”, “”, “”, “blue-green”)

with the variations separated by commas within the quoted string. You can leave any of name, er_name, and ish_name blank if you don’t want to bother with the variations, or if a new variation is the only thing you want.

The execution sequence is evaluate the definition, delete any old definitions that conflict with new ones, and then enter the new names. This means that

Define_Color_Name(“red”, “redder”, “reddish”, “darkish red”)

is a reasonable way to make the standard “red” color a little darker than it was, since the “darkish red” is evaluated before the “red” is deleted.

If an absolute color-space location is used for definition, the string should look like “X=val Y=val Z=val”, where the “val“‘s are floating-point numbers and the “XYZ” is either of the following:

If an absolute color-space location is used for definition, the string should look like “X=val Y=val Z=val”, where the “val“‘s are floating-point numbers and the “XYZ” is either of the following:

------------------------------------------------------------------------------------
"HLS" - For hue, lightness, and saturation (a "double cone", with black and white at the tips).
"HSV" - For hue, saturation, and value (a "single cone" standing on its point, with black at the tip and white at the center of
the base). "HIC" - For hue, intensity, and chromaticity (a cylinder, with black and white at the two ends). "RGB" - For red,
green, and blue (a cube, with white, black, and six primary colors at the corners).
------------------------------------------------------------------------------------

All numeric values must be in the range of zero to one inclusive, except for hues, which range from zero to 360degrees. If a hue is outside this range, the system normalizes the value.

UnDefine_Color_Name() , given just one name, removes that name from the system along with the whole group of related name variations that were defined at the same time. If you do want to list things to UnDefine_Color_Name() , that’s permissible too.

Refer to the entry on color-naming, in the User’s Manual, for more details on the grammatical rules for the definition.

Define_Color_Name() replaces Define_Color. The naming was changed in order to make the names of the “Show Color” routines more consistent.

NOTES

The limit on the length of color names is large (on the order of 2^16 characters.)

A warning is given for redefining an already existing name.

If you write library subroutines, you might find it appropriate to use a standard prefix for all the color names you choose. Then your colors can’t accidentally overlap with those chosen by the programs that will call your routines.

ISO Latin-1 characters may be used in color names. See Table 6.1 in Insert_Text() .

See also

HC_Set_Color, HC_Set_Color_Map, HC_Set_Color_By_Value, HC_Show_Color_Name.

Parameters

name – - Simple name to be added to the list of definitions.
er_name – - The “er” (1st degree) combining form of the simple name above. E.g., “red-er” is to be spelled “REDDER”.
ish_name – - The “ish” (2nd degree) combining form, as in “REDDISH”.
definition – - The actual color, either in terms of colors that already exist, or as an absolute location in a color space.

void HC_Define_Driver_Config(char const *driver, char const *id, char const *version, char const *config)

Sets up driver device-dependent configuration.

Define_Driver_Config invokes certain driver configurations, such as graphics-card-dependent logic, withough forcing the user to recompile the driver code. In order to take effect, this function must be called before driver startup. After the first update, the driver config cannot be changed without shutting down the driver and starting a new one. This feature is only available for 3D drivers (DX11, OpenGL, and OpenGL2).

DETAILS

This function should not be needed unless there are specific hardware problems that must be avoided. Unless absolutely needed, it is best not to attempt to use this unless instructed by Tech Soft Support.

driver, id and version can all take ‘*’ as a wildcard.

version should be formatted as a list of decimal-separated integers (e.g. “8.5.7.4” or “8.301”), optionally prepended with >=, <=,!=, > or < to specify the comparison type. The comparison between specified and actual versions proceeds one integer (repeat: one complete integer, not just one digit) at a time, and halts when it either comes to the end of one list or the other. If it reacheas the end or a “*”, the versions are considered equal. The supplied string is considered a match on its non-wildcard characters if the actual driver string as extracted from the registry or environment is equal to or greater than the supplied list. Examples:

99 is less than 8.301
4.9 is less than 8.5.7.4
5 is equal to 8.5.7.4
4.7.4 is equal to 8.5

If no comparison type is given, >= is assumed.

config is a comma-separated list of options. Valid choices for config include:

reset

Restores the built in defaults for Radeon cards. For example:

HC_Define_Driver_Config ("opengl", "radeon*", "*", "reset");

flush

Removes all configs for Radeon cards. For example:

HC_Define_Driver_Config ("opengl", "radeon*", "*", "flush");

tristrip minimum = ddd

Controls when tristrips or triangle primitives are used to draw tristrips. Driver dependent. Currently supported only with OpenGL.

display list tristrip minimum = ddd

Controls when tristrips or triangle primitives are used to draw tristrips. Driver dependent. Currently supported only with OpenGL.

flat tristrip minimum = ddd

Controls when tristrips or triangle primitives are used to draw tristrips. Driver dependent. Currently supported only with OpenGL.

flat display list tristrip minimum = ddd

Controls when tristrips or triangle primitives are used to draw tristrips. Driver dependent. Currently supported only with OpenGL.

general tristrip minimum = ddd

Sets all four of the above setting to one value. Driver dependent. Currently supported only with OpenGL.

config = (token, token, token, …)

A list of special strings to control the way the driver behaves. In general these are workarounds for hardware bugs. Driver dependent.

<strong>Valid choices for OpenGL 1 ("opengl1_deprecated" driver):</strong>

Valid choices for DirectX11 are:

XBIT_NONE
XBIT_FORCE_SM3
XBIT_SLOW_PIXEL_OIT
XBIT_FORCE_STANDARD_MULTISAMPLE_PATTERN
XBIT_BAD_RESOLVE_TO_BACK_BUFFER
XBIT_BAD_DEPTH_ONLY_CLEAR
FORCE_DEFAULT_SOFTWARE

OpenGL 2 users:

XBIT_NONE
XBIT_BAD_MSAA_SPRITING
XBIT_BAD_NON_POWER_OF_2_TEXTURES
XBIT_TEXTURE_SIZE_OFF_BY_ONE
XBIT_BAD_GLSL4_SAMPLER_CUBE
XBIT_FORCE_GLSL2
XBIT_BAD_BLIT_FILTER
XBIT_BROKEN
XBIT_NO_ANTIALIAS
XBIT_AMD_BAD_DOUBLE_PRECISION
XBIT_BAD_POINT_SPRITES
XBIT_AMD_BAD_RGB24_TEXTURE
XBIT_ANDROID_BAD_BLIT_TO_BACK_BUFFER
XBIT_BAD_CONTEXT_SHARING
XBIT_FORCE_NO_DEPTH_COPY
XBIT_BAD_SHADER_DERIVATIVES *

Please note that FORCE_DEFAULT_SOFTWARE is not an available option for OpenGL 2 drivers.

See also

HC_Set_Driver_Options

NOTES: No show type interface defined yet.

Parameters

driver – - The driver to configure.
id – - The driver ID string.
version – - Constraints (by default, a lower bound) on the driver version.
config – - A pre-defined configuration string of comma-separated values. See details for more.

void HC_Define_Error_Handler(Void_Routine handler)

Creates a legal name for an error handler that captures HOOPS error reports.

You can define as many error handlers as you please. Each error handler is called for each message, from newest handler to oldest handler. When HOOPS is started up, the Report_Error() routine is defined for you as a default handler. Messages won’t just fall on the floor without being seen. It prints out the message in a system-dependent way in a place the user can (hopefully) see it. If your own routine does the same job better, feel free to UnDefine the default handler.

DETAILS: There are many programming mistakes that HOOPS might trip over. Define_Error_Handler() allows the program to look at the error messages going by, and perhaps to do something about them.

When a fatal error happens, HOOPS first calls all the declared error handlers, then exits to the operating system. To avoid this program exit your handler must do something drastic, such as calling Reset_System() and then the C routine “longjmp”.

The parameters passed to the handler routine follow (in order):

“category” An integer. Identifies the general category the error belongs to, out of those defined in the hpserror.h include file. For example, memory errors fall in the HEC_MEMORY error category. “specific” An integer. Identifies the specific error out of those defined in the hps error.h include file. For example, running out of memory. HES_OUT_OF_MEMORY, is a specific memory error in the HEC_MEMORY category. “severity” An integer. Indicates the seriousness of the offense. In particular, a “0” means the message is just informational, a “1” means the message is a warning (but the system is going to go ahead with the operation), a “2” is a generic “error”, and a “3” is a fatal error (indicating that something is drastically amiss, and there’s no reasonable way to continue.) “msgc” An integer. Indicates how long msgv is. “msgv” An array of pointers to character strings, with one string for each line of the message. “stackc” An integer. Indicates how long stackv is. “stackv” An array of pointers to character strings, where each string is the name of a currently active HOOPS routine. The originally called routine would be the first one in the list. ————————————————————————————— *

If you want to capture some errors, but let Report_Error() take care of the rest, you might try removing Report_Error() as a handler, and then calling it manually from your own service routine as needed.

NOTES

On some operating systems the handler routine may have to be written in C, no matter what the calling program is written in.

A warning is given for redefining an already existing handler.

See also

HC_Report_Error, HC_Define_System_Options.

Parameters: handler – - Address of a new error-handling routine, a routine returning nothing

void HC_Define_Exit_Handler(Void_Routine handler)

Allows the program a chance to “clean up” upon termination.

“Exit handlers” are subroutines called automatically as part of the standard program termination sequence. They are handy for performing functions such as marking files as possibly incomplete, freeing system resources, and sending final goodbye messages to the user.

DETAILS

The defined exit handlers are called (in sequence from newest to oldest) if the exit is due to a HOOPS fatal error, a call to Abort_Program() , or a call to Exit_Program() . HOOPS will also try to catch program exits that occur for other reasons, outside of HOOPS, but it may or may not be able to do that, depending on your operating system.

If a handler calls Reset_System() (to be sure, for example, of getting a final message to the screen) the system completes the calling of the other exit handlers before doing the Reset and returning to the initial handler.

NOTES

If an error or an exit occurs during the execution of an exit handler, the remaining handlers, if any, will be called. Control will not return to the exiting handler, nor will it be called recursively. Handlers can be called once per definition. It is permissible to reactivate a handler (and possibly fall into a recursion loop) by calling Define_Exit_Handler() from within the handler.

“Escaping” from an exit (by unwinding the calling stack, for example) is system-dependent and beyond the scope of this manual.

Reset_System() is defined as an exit handler during the system’s startup sequence.

A warning is given for redefining an already existing handler.

See also

, HC_Define_Error_Handler, HC_Reset_System, HC_Abort_Program, HC_Exit_Program, HC_Define_System_Options.

Parameters: handler – - Address of a new exit-handling routine. routine returning nothing

void HC_Define_Font(char const *name, char const *options, int data_length, char const data[])

Describes a specific set of simple geometry to be used as the actual shapes when drawing text characters.

Define_Font() allows you to specify specific shapes for drawing individual text characters. The data consists of a header section with general information about the font, followed (usually) by descriptions of the individual characters. The options may alter the exact data format. The general form of the data is to represent the characters as drawings within a grid from -127 to 127 in both the X and Y directions. For convenience, many fonts define a much smaller cell size within this range. The current built-in fonts, for instance, are defined in a “standard” box. The box is 0 to 50 vertically, and 0 to (an average of) 30 horizontally, with descenders extending as much as -15 and ascenders as high as 55.

DETAILS

Define_Font_By_Reference() will not make an internal copy of the character data. Instead, it will remember where your data is located.

The following options are recognized:

encoding = choice Specifies the mapping between character codes and their shapes. The same choices can be specified here as for the “encoding” field of Insert_Text_With_Encoding() . Note that a font can be used to draw text only if its encoding is compatible with the encoding specified when the text was inserted. The default is “ISO Latin One” if not specified.

[no] lookup [= callback name] Defines a routine called by the system when it needs data about a specific character in the font. The default, “no lookup”, indicates the system should search the data it was given for the necessary information. When a lookup is specified, it is called to provide the address of the data for the specified character. In this case, the system ignores any character specific information (if any) following the header information. The format of the lookup functions is

 void lookup (
     const char *font,
     const char *data,
     unsigned short character,
     unsigned char const **address
)

The lookup function should fill in “address” with the address of the first byte of the data for the requested character in the specified font. The first byte for the character is that of the “value” field (see character data description below). The data is passed to the lookup routine to do as it pleases. Since the system ignores anything after the header, it is a convenient place to store extra information for the routine. The data_length argument should include any such extra data, which will be copied and later returned. (The By_Reference() version does not copy, instead it passes the original address of the data).

The header portion of the data consists of the following required data (each specified as a single byte):

revision: An indication of the overall format of the data. The only value allowed is 3.

height: The nominal height of the font. This is usually the size of capital letters.

width: A nominal character width for the font.

spacing: The amount of space that should be placed between characters.

The per-character data consists of a short header with sizing information, followed by a list of drawing codes and coordinates. The header format (with each value specified as a byte unless otherwise noted) is as follows:

value: The index associated with this character. If the font encoding is “ISO Latin One”, the value is specified as a single byte. Otherwise, (for all currently recognized encodings) the value is given as two bytes, with the high byte first.

width: The width of this character.

x offset / y offset: The position of the left edge and baseline of the character. Usually specified as 0,0 but might be otherwise if the font is being converted from another format, or if the character cell is too large to be based at the origin.

descender: The lowest point on the character.

ascender: The highest point on the character.

The drawing codes consist of a one byte code, possibly followed by other data. The codes currently recognized are as follows:

0 Polyline - The actual number specifies the number of X, Y coordinate pairs, will be drawn as connected line segments. A one

point polyline tries to draw a single dot. 0 Termination - This ends the definition of this character.

-1 Start fill - Instead of drawing lines that follow, the lines will be stored as the outline of a region to be filled as a polygonal area.

-2 Restart fill - The current outline will be closed and filled, and a new one will be started.

-3 End fill - The outline will be closed and filled, and normal line drawing mode will resume. A -3 is added at the end of a character, if needed.

-4 Ellipse - Two X,Y coordinate pairs are specified. These define the extents of the rectangle surrounding the ellipse. If fill mode is on, the ellipse is drawn filled, and the current outline (if any) remains unchanged.

-5 3 Point arc - Three X,Y pairs are specified, indicating the start, intermediate, and end points of the arc.

-13 Restart path - The current path (loop) is to stop and a new one will be started.

EXAMPLES

The definition of part of a (crude) font might have data similar to the following example (assuming options of “encoding=ISO

Latin One, no lookup”):

general header
        3 50 30 20
left parenthesis
        40
        header
                10 0 0 -10 55
        drawing
                -5 10 -10 0 22 10 55    arc from bottom to top
                0
number 8
        56
        header
                30 0 0 0 50
        drawing
                -4 0  0 30 30  bottom circle
                -4 3 30 27 50  ellipse(slightly flattened)
                0
capital A
        65
        header
                30 0 0 0 50
        drawing

3 0 0 15 50 30 0 up & down slants 2 6 20 24 20 cross stroke 0

See also

HC_Show_Font, HC_Set_Text_Font, HC_Define_Callback_Name, HC_Insert_Text_With_Encoding

Parameters

name – - The name to be associated with this font definition. Passed by reference always.
options – - A string describing general characteristics of the font. Passed by reference always.
data_length – - Number of bytes in data.
data – - Information about extents of character shapes and how to draw them. Passed by reference always.

void HC_Define_Font_By_Reference(char const *name, char const *options, int data_length, char const data[])

Similar to Define_Font(), but avoids creating an internal copy of the font within HOOPS memory.

See also

HC_Define_Font()

Parameters

name – - The name to be associated with this font definition. Passed by reference always.
options – - A string describing general characteristics of the font. Passed by reference always.
data_length – - Number of bytes in data.
data – - Information about extents of character shapes and how to of bytes draw them. Passed by reference always.

void HC_Define_Glyph(char const *name, int data_size, char const data[])

Describes a set of simple geometries which can be later used to define a custom marker, edge, or line style.

Define_Glyph allows users to define a simple set of geometries that can be used to create a custom marker, edge or line style. The data consists of a general header and then specific information about each single piece of geometry in the glyph. A glyph definition is local to a segment and is inherited like any other attribute. Each glyph works off a 256*256 canvas with the defining geometry being located at the center of the canvas at (0,0). When defining the geometry, users should define each location (x, y) such that x and y are in the range of (-127, 128). The colors of the geometry can be either set within the glyph definition or by using the marker, edge and line color and contrast color defined within the containing segment.

DETAILS

The data block header consists of three char values. The first is the nominal radius that defines the radius of the glyph for the purpose of sizing and selection while the second two numbers are the x and y offsets respectively. These offsets allow users to position the glyph relative to the actual insertion point.

The second block in the data block consists of a series of codes which may have optional arguments. Both the codes and their arguments are chars. The various codes and their associated arguments are:

------------------------------------------------------------
"n"     where n is a signed char
"n>1"   A polyline consisting of n points.  This code is then
       followed by a list of n (x, y) pairs which define
       the polyline within the glyph canvas.
"1"     A dot.  This code is followed by the (x,y) location
        of the object within the glyph canvas.
"0"     Termination of glyph definition.  This must be at
        the end of all glyph definitions.
"-1"    Start fill. Closed geometry subsequent to this will
        be filled.
"-2"    Restart fill.
"-3"    End fill.
"-4"    Ellipse.  This code is followed by 2 (x,y) which
        define the lower left and upper right corner of the
        rectangle which contains the ellipse within the glyph
        canvas.
"-5"    Circular arc.  This code is followed by 3 (x,y) pairs
        which define the start, an intermediary, and the end
        point of a circular arc on the glyph canvas.
"-6"    Infinite line.  This code is followed by 2 (x,y) pairs
        which are located on the line segment within the glyph
        canvas.
"-7"    Infinite ray.  This code is followed by 2 (x,y) pairs
        the first of which defines the start point of the ray
        and the second of which is located which are located on
        the ray on the glyph canvas.
"-8"    Start contrast color. The geometry subsequent to this
        will be colored according to the owning geometries
        contrast color setting.
"-9"    Start normal color. The geometry subsequent to this
        will be colored according to the owning geometries'
        color setting.
"-10"   Start RGB color.  The geometry subsequent to this will
        be colored with the rgb value that is defined in the
        (r,g,b) triplet which is defined in the values
        immediately following this code.
"-11"   Start indexed color.  The color of the geometry
        subsequent to this is the index which is defined in
        the value immediately following this code.
------------------------------------------------------------

A simple example:

const char crosshairs[] = {10, 0, 0, 2, -10, 0, 10, 0, 2, 0, -10, 0, 10, 0}

HC_Open_Segment("?Picture");
   HC_Define_Glyph  ("crosshairs", sizeof(crosshairs),  crosshairs);
   HC_Set_Marker_Symbol("crosshairs");
   HC_Insert_Marker(-0.5, 0.0, 0.0);
HC_Close_Segment();

See also

HC_Show_Glyph, HC_Define_Line_Pattern

NOTES: To ensure optimal performance in the drawing of these objects, users should try and minimize the amount of color attributes that are set within a glyph. This is best done by organizing the different geometries according to their colors.
RESTRICTIONS

Parameters

name – Name of the custom marker, edge, or line style.
data_size – Size of data
data – Glyph definition described below.

void HC_Define_Image_Glyph(char const *name, char const *definition)

void HC_Define_Line_Style(char const *name, char const *definition)

Allows the user to create a custom line style using a combination of lines, blanks, glyphs, and attributes.

Define_Line_Style allows users to create custom line styles using combinations of user-defined glyphs and a number of pre-arranged glyphs, lines, and modifiers. These are the basic ingredients for Parallels, which in turn make up the style definition:

DETAILS

definition = "[ Parallel ] [, Parallel ] [, Parallel ] [, Transformed ]"

Parallels

The definition string, or line style definition, is a comma-separated list of “parallels” that have optional parameters and/or modifiers, as follows:

Parallel = [Caps-n-Arrows]
           [+/-ddd gsu [fixed] offset,]
           [+ddd gsu [fixed] weight,] [fit,]
           [segmented,] [,absolute[weight|length]] [join,]
           [Element] [,Element]...

Caps-n-Arrows See section below on Caps and Arrows.

+-ddd gsu Generic size units (.05 oru, 12 pixel, etc). For valid options see Set_Text_Font().

”fit = center / stretch” Specifies the method by which line patterns can be made to fit evenly between endpoints. The first method, “fit = center”, attempts to center the pattern between endpoints so that the first element occurs both at the beginning and the end. This method assumes that the first element makes up at least half of the total length of all elements combined. If this assumption is not met, the method loses effectiveness. The second method, “fit = stretch”, stretches the pattern between two line segments by making adjustements to the length of the elements and therefore honors the endpoints at the expense of the pattern’s definition.

”fixed” If the element is a glyph, it will have a fixed orientation and will not be affected by the direction of the underlying line.

offset Defines the distance between parallel lines. This modifier should immediately follow the “parallel” setting. If fixed, then the local segment’s line weight does not scale the offset.

weight Sets line weight for a parallel. This should immediately follow the parallel setting. If fixed, then the local segment’s line weight does not scale the weight.

”segmented” Makes the pattern reset for each segment of a polyline

”absolute [weight | length]” Prevents device- or driver-dependent scaling from affecting element attributes that have been specified in pixels. In other words, “absolute” pixel sizes, weights, etc. will be honored. Specifying “absolute” will set “absolute length” and “absolute weight”.

”join” Makes the current parallel follow the visibility rules of middle glyphs. This can be useful for drawing arcs and curves.

”parallel” Signifies the beginning of a new parallel within this line style.

Elements

In the examples above, “dash” is an Element that is modified by the properties of the parallel. Elements consist of a shape (line or glyph) with a modifier (length or size), as follows:

Element = [+ddd gsu] dash  or
          [+ddd gsu] blank or
          [+ddd gsu] contrast or
          [+ddd gsu] glyph_name [,inline|inset] [,mirror] [,rotation=x] [fixed]

+ddd gsu Length or size of the element in generic size units (.05 oru, 12 pixel, 20%, etc). For valid gsu options see Set_Text_Font().

”blank” An invisible line. If no length specified then the blank will be infinite and stretchable.

”contrast” A visible line colored according to the current line-contrast or edge-contrast color settings (see Set_Color()). If no length specified then the contrast will be infinite and stretchable.

”dash” A visible line. If no length specified then the dash will be infinite and stretchable. The color of the dash will be specified by the current line/edge settings.

glyph_name A user-defined glyph or build-in marker. If no size is specified, the glyph uses the current marker size setting. The following settings are specific to glyphs:

”inline” - The line pattern is resumed after leaving space for the glyph
“inset” - The line pattern is snipped to the glyph’s nominal radius
“mirror” - Flips the glyph about its X-axis before applying any rotation element.
“rotation = x” - The additional angle in degrees the glyph is rotated about the line vector.
“fixed” - The angle of rotation of the glyph will not be affected by the line vector.
“weighted = [+ddd gsu]”
- This sets the line weight for the strokes used to draw the glyph. For example, “arrow = X,

weighted=3 pixels” will draw a solid line with a heavy X at each end.

Caps and Arrows

The endpoints of custom linestyles may be controlled with a number of settings that come first in the definition of a parallel. Individual parallels in a definition can have unique cap and arrow settings. See the examples in the NOTES section for usage.

start cap = glyph_name The glyph to be used at the start of the polyline

end cap = glyph_name The glyph to be used at the end of the polyline

caps = glyph_name The glyph to be used for both the start and end caps.

start arrow = glyph_name The glyph to be used at the start of the polyline

end arrow = glyph_name The glyph to be used at the end of the polyline. This glyph will be rotated by an additional 180 degrees.

arrows = glyph_name The glyph to be used for both the start and end of the line.

middle = glyph_name The glyph at the mid-point of the polyline line segments.

glyph = glyph_name The glyph to be used for the start, end, and middle of the line.

Transformed Option

By default, user-defined line styles are screen-oriented (2D space). If the “transformed” key word is used in the style definition, HOOPS will draw the pattern in 3d space. Users can set the orientation vectors for the pattern via the “orientation” setting of Set_Geometry_Options(). The “transformed” setting can only be used on polyline primitives. See example #7 below for usage.

Please note that since line patterns are projected on an arbitrary plane, transformed line patterns can lead to some surprises. For one, segments of polylines will have non-uniform dash/blank lengths if they are at different angles to the projection plane. This is most noticeable when a blank eats up an entire segment. This is also true for glyph spacing.

Custom line styles are local attributes of a segment and inherit as such.

When a glyph is applied to a line style, by default it is positioned so that it is perpendicular to the line normal. Additionally, the “hot spot” for the glyph is honored and a “12 O’Clock” orientation is assumed.

If a glyph follows another glyph in a line style definition there is an implicit blank the length of the sum of their two radii between them.

Pixel-based patterns that will not divide evenly by 16 will draw more slowly under OpenGL than patterns that will divide evenly.

Example 1: A solid line (actually a dash without blanks) of weight=1 is the default parallel. Therefore the line style resulting from an empty string passed as the definition will be a single, solid line of weight one (1 pixel). However, let’s say we want to create the default solid line style with double weight:

NOTES
EXAMPLES

HC_Define_Line_Style
(
  "solid_line",
  "2 pixel weight,"
  "dash"
);

Note that the example does not use the world ‘parallel’ as the first directive in the definition. This is because ‘parallel’ is implicit at the beginning of a definition.

Example 2: The double-line version of the above example, with a 20 pixel separation, would look like this:

HC_Define_Line_Style
(
  "double_solid_line",
  "2 pixel weight,"
  "dash,"
  "parallel, 20 pixel offset, 2 pixel weight,"
  "dash"
);

Note that in this example, the second instance of “dash” (the second parallel) must be preceded by “parallel” to identify the beginning of a new parallel, whereas in the first instance this is implied.

Example 3: The following example creates and sets a scalable line pattern that alternates between a line segment, a blank, and a line segment in the segment’s contrast line color:

 HC_Define_Line_Style
 (
   "myLineStyle",
   "0.1 oru dash,"
   "0.1 oru blank,"
   "0.1 oru contrast"
);

 HC_Set_Color ( "lines=red, line contrast=blue");
 HC_Set_Line_Pattern("myLineStyle");

Example 4: Another example creates a line which has arrow heads at either end:

 const char Arrow[] =
 {
   10, 0, 0, -1, 4,
   -10, 0, 0, 10, 10,
   0, -10, 0, -3, 0
 };

 HC_Define_Glyph
 (
   "triangle",
   sizeof(Arrow),
   Arrow
 );

HC_Define_Line_Style
(
   "myLineStyle",
   "arrows = 0.1 oru triangle,"
   "dash"
 );

 HC_Set_Line_Pattern("myLineStyle");

Example 5: Using parallels, it is very easy to create a triple-line style:

 HC_Define_Line_Style
(
  "myLineStyle",
   "dash,"
   "parallel, 0.05 oru offset,"
   "contrast,"
   "parallel, -0.05 oru offset,"
   "contrast"
 );

 HC_Set_Color("lines=red, line contrast=blue");
 HC_Set_Line_Pattern("myLineStyle");

Example 6: This example uses the “fixed” setting to force one of the parallels to be always 5 pixels from the center-line, while the other will be affected by the local line weight and consequently be 10 pixels from the center-line.

HC_Define_Line_Style
(
  "myLineStyle",
  "dash,"
  "parallel, 5 pixel fixed offset,"
  "contrast,"
  "parallel, -5 pixel offset,"
  "contrast"
);

HC_Set_Color("lines=red, line contrast=blue");
HC_Set_Line_Pattern("myLineStyle");
HC_Set_Line_Weight(2.0);

Example 7: The following example defines a simple pattern that consists of 2 dashed polylines with an offset in 3D space such that both lines lie on a plane defined in Set_Geometry_Options():

HC_Define_Line_Style("3d_parallel", "dash, parallel, 5 pixel offset, dash, transformed");

The names “0” - “9” are reserved for backward compatibility with the hidden line pattern specification however you can use line style names like “00”, “10”, “21” etc.

RESTRICTIONS

See also

HC_Define_Glyph, HC_Show_Glyph, HC_Show_Line_Style

Parameters

name – Name of the custom line style.
definition – Line style definition described below.

void HC_Define_Shape(char const *name, int data_size, float const data[])

Defines a shape to be used for the background of a text annotation.

The following snippet shows how to define a text box with trimmed corners: ../../_images/corner_trimmed_box.png

DETAILS

    float const clipped[] = {3,  8, 1,  0, 1,  0, 1,  0, 1, 0, 0,  0,  1, 1, -1, 0, 0,  0,  1, 1, -1, 0, -1, 0, 1, 0,
                             -1, 0, -1, 0, -1, 0, -1, 0, 0, 0, -1, -1, 1, 0, 0,  0, -1, -1, 1, 0, 1,  0, -1, 0, 0};
    HC_Define_Shape("clipped", countof(clipped), clipped);

    HC_Open_Segment("clipped");
    HC_Set_Text_Font("background=shape=clipped");
    HC_Insert_Text(-0.8, 0.8, 0, "corner trimmed box");
    HC_Close_Segment();

The first number in the array is a 3, indicating that each coordinate will be defined with three numbers. The first number is a scale of the bounding in the horizontal direction of the coordinate. The second number is the the scale of the bounding in the vertical direction of the coordinate; in the case of mult-line text, the vertical bounding refers to the height of a single line of text. Lastly, the third value is a margin; by default, margins are defined such that a value of “1” would be equal to 50% of the height of a text character. (For more information on margins, including how to change the default settings and how they are applied, please see the Set_Text_Font_options function.)

The number 8 indicates that there will be 8 points used to define the polygon, with each point consisting of two coordinates. In this case, each point is defined with six numbers: the first three define the X coordinate and the last three define the Y coordinate.

Finally, a terminal 0 indicates that the definition is complete. These numbers are explained in detail in the table below.

The format codes for shapes are the following:

Format code	Elements	Example
6	x bounding of the coordinate, y bounding of the coordinate, and four margin values	Each

coordinate of a point is defined with six numbers: 1, 0, 1, 0, 1, 0 (A point is defined with two coordinates) | | 5 | x/y bounding + three margin values | 1, 0, 1, 0, -1 | | 4 | x/y bounding + two margin values | 1, 0, 1, 0 | | 3 | x/y bounding + one margin value | 1, 0, 1 | | 2 | Single coordinate value (applies to both x and y bounding of the coordinate) | Same as format 3, except it has no margin value. | | 1 | Single coordinate value (applies to both x and y bounding of the coordinate) | This format is provided for convenience; each coordinate in the point is defined with a single value: 1, 1 (Format 1 includes the default margins.) | | 0 | Same as format 1. | | -3 | x bounding of the coordinate, y bounding of the coordinate, and a radius value | 0, 1, 0.5 | | -4 | x bounding of the coordinate, y bounding of the coordinate, a radius value, and a margin value | 0, 1, 0.5, -0.5 | | -5 | x bounding of the coordinate, y bounding of the coordinate, a radius value, and two margin values | 0, 1, 0.5, 0, -0.5 | | -6 | x bounding of the coordinate, y bounding of the coordinate, a radius value, and three margin values | 0, 1, 0.5, 0, 0, -0.5 | | -7 | x bounding of the coordinate, y bounding of the coordinate, a radius value, and four margin values | 0, 1, 0.5, 0, -0.5, 0 |

The opcodes for shapes are as follows:

Type	Op Code	Required Elements	Notes
Polygon	3 or higher	Three or more points	A polygon can be defined

For an example of how to insert an anchored leader line on an annotation shape, please see the Insert_Text_Leader function.

Parameters

name – - The name being assigned to this shape definition.
definition_length – - The number of elements contained in the definition array.
definition – - Array of floating point numbers representing the shape definition, including the shape type (e.g., polygon, circle, ellipse, circular arc, etc.), the number of elements in the shape definition(s), the shapes’ points, radii and other related settings, and a terminal 0 at the end of the array. Please see the table below for more details.

void HC_Define_System_Options(char const *list)

Controls non-graphics system behavior.

“System options” are a group of status settings that don’t have anything directly to do with graphics - they just control how the system reacts to some error and debugging situations. “System options” are defined system-wide - they are not a part of the graphics segment tree.

As usual, the options are specified as a list of items separated by commas, and uppercase vs. lowercase doesn’t matter. The options are as follows:

application =

This provides a place to record the name of the currently running application program. This might be convenient for utility routines. For example, a hardcopy utility routine might want to generate some labelling information.

If “application” is not set explicitly, HOOPS uses the environment variable HOOPS_APPLICATION. If that’s not available either, HOOPS asks the operating system for the file name of the currently executing image. If that’s not available either, then a blank string is used.

[no] automatic geometry boundings = [= on | off] (REMOVED)

This option has been removed. By default, Visualize now automatically updates geometry bounding; this setting cannot be turned off.

[no] bounding volumes [= on | off]

This option determines whether or not HOOPS calculates bounding volumes and uses them in rendering and processing selections. Use of bounding volumes improves drawing and selection performance but requires more memory. The default is “bounding volumes”. See Show_Bounding_Info() for more details.

[no] C string length = nnn

When HOOPS is called from a C language program, passed a buffer, and asked to return a string value in the buffer, it can’t tell how big the buffer is. The C language doesn’t provide that information automatically. If the buffer is too small for the string being put into it, the string will run off the end and overwrite other memory. Unfortunate results might ensue.

One solution is to make all your buffers “ample” in size. Alternatively, you can pick a standard size for your buffers and use “C string length” to tell HOOPS what that size is. Then, if a return string exceeds that size, HOOPS will know to issue a clean warning message and will avoid walking on memory.

The “C string length” is the total buffer size - it includes the terminating null byte. The default is “no C string length”.

camera near limit = (fff)

Sets the default camera near limit. Default value is “-0.001”. To get the pre-HOOPS v15 behavior set the value to 0.0001 for an OpenGL/D3D driver, or 0.05 for all other drivers.

[no] code generation [= on | off]

This is a special option available for generating debuggable HOOPS programs. When this option is activated, usually though the HOOPS_SYSTEM_OPTIONS environment variable, HOOPS generates a C program in addition to drawing to a device. The C program, code.c, is a sequential enumeration of HOOPS calls. This is one way to generate test cases for Tech Soft 3D Technical Support without having to send entire applications. Obviously, the default is “no code generation”.

code generation comment = (xxx)

This option has no effect at all other than to show up in code generation output. It is intended to allow users to inject general information about what is going on in their programs into the code generation trace. This option has no default.

[no] code generation directory = ‘path’

Allows the user to specify the directory in which the ‘code generation’ source files should be placed. The default is “no code

generation directory”.

[no] conserve memory [= on | off | memory_option ]

“conserve memory = on” means use all available memory suboptions. Legal values for memory_option include:

face list = on|off - Instructs HOOPS to discard face list information once a shell’s tristrips have been processed (after the shell has been drawn for the first time).
facings = on|off - Halts the generation of temporary ‘screen plane facings’ flags used for determining front & back sides of faces. This latter sub-option saves memory at a slight calculation expense.
circles = on|off - Instructs HOOPS to maintain a lightweight representation of circle-based geometries that have a z-value of zero. This reduces memory footprint with one notable restriction: lightweight circle-based primitives can not be edited using any of the Edit_XXX routines.
polyedges = on|off - Asks HOOPS to draw edges with the tristrip data rather than generating separate polyedge structures. This setting only has effect when the (1) there are no per-edge attributes, (2) the weight of the edges are 1, and (3) there is an edge visibility setting of “on”, “adjacent” or “nonculled”. Currently this option is supported only by the OpenGL driver.

The default is “no conserve memory”.

[no] continuous update [= on | off ]

“Continuous update” causes Update_Display() to be called at the end of each and every HOOPS call that might have changed the picture. This can be useful when there’s a problem occurring in your picture and you’re not sure where in your program the problem originated. When “continuous update” is on, you can step along in a debugger and watch the picture unfold. This option can slow down the running time of your program. The default is “no continuous update”.

[no] debug [= (ddd)]

Enables special (not yet fully supported) capabilities. The definitions of the debug bits change from release to release and so please contact support for a list of specific options. Keep in mind that debug bits set through this API are not cumulative, so subsequent debug bit settings will replace everything. If you wish to have a cumulative effect you should look at either the ‘clear debug’ or ‘set debug’ options. The default is “no debug”.

Bit Mask	Notes
0x00000004	Disables hardware-based visual selection. Please note, you will lose any performance gains hardware-based

visual selection would typically provide. |

[no] deleted key callback = ‘callback name’

The callback name refers to the callback defined by Define_Callback_Name(). Whenever an object with a key is deleted, the function associated with the callback name is called with the key as its argument. If the key is a segment with children, the function will be called on its children first. Note that the deletion does not occur until the next update. Consequently, you may get unexpected keys for unknown/temporary geometry within your callback.

[no] disable ambient material [= on | off]

If set, ambient light bypasses the usual modulation by the material. This would, for example, allow red ambient light to affect a blue surface, and/or any color ambient light to contribute to a black surface. The default is “no disable ambient material”.

[no] dpi scale factor [=<float>]

When set, this option overrides the default value for the system. It is used in point size calculations. A dpi scale factor of 1.0 is equal to 96 dpi. No restores the default value.

driver config file [= filename]

The filename contains a path to a file which can be used to force device specific behavior by our 3D drivers. The file is plaintext and the contents must be written in a specific format. The format corresponds to the arguments that Define_Driver_Config() takes. It can contain any number of sets of arguments. Each set of arguments will be passed into a call to that HC function. The calls will be made in the order they appear in the user’s config file. This matters because of the function’s wildcard matching - entries should go from general to specific. They also occur after 3dGS’ internal settings and consequently supersede them.

The options must be listed in a specified order: named DRIVER, ID, VERSION, and CONFIG (all caps). Each key word must be followed by a colon, a space, and the value. Option and value must be on a single line regardless of length of option. A blank line must be in between chunks. Empty string is a valid CONFIG, but the line “CONFIG: ” must be included.

Example config file contents:

DRIVER: dx11
ID: RADEON*
VERSION: *
CONFIG: config=(BAD_MSAA_SPRITING)

DRIVER: dx11
ID: FIREGL*
VERSION: *
CONFIG: config=(BAD_MSAA_SPRITING)

DRIVER: opengl
ID: *
VERSION: *
CONFIG: general tristrip minimum=3

By default no driver config file is provided.

clear debug = (ddd)

Removes the specified debug bit from the current debug value.

set debug = (ddd)

Adds the specified debug value to the existing debug value.

soft memory limit = (ddd)

Specifies the soft memory limit, in megabytes. Visualize will trigger an informational event when it allocates more memory than specified here. You should set an error handler to intercept this event and respond appropriately.

[no] event checker [= address ]

An “event checker” routine, if provided, is called by the system whenever Await_Event() or Check_For_Events() needs input. It is an opportunity for your program to put input from an unusual source (an event recorder, an unsupported brand of tablet, etc.) into the HOOPS queue manually, via the “Compute Selection” or the “Queue” routines.

On most systems the routine must be written in C. The routine is called with no arguments. The “address” is specified as a decimal number.

Usage of this option is only recommended for standalone HOOPS Programs. For applications which use the “use

window ID” Driver_Option the recommended path for breaking an update is to use the capabilities exposed by the “exit update” driver option.
The default is “no event checker”.

[no] extended font search [= on | off ]

If “no extended font search” is set, it may potentially restrict the number of fonts available but it also puts a cap on how long HOOPS will spend loading fonts. HOOPS will only use true-type fonts that can be found through system-dependent font lookup.

On Windows, this means that fonts available will be restricted to what can be looked up from the windows registry. Windows only keeps track of the fonts that are installed in the standard font directory.

On Mac OS X, the font name (see Set_Text_Font()) needs to be the “postscript name” for the font. This is an identifier that is guaranteed to be 8-bit (i.e. no wide characters) and globally unique on the system. It is, however, case sensitive, so the font name will usually need to be guarded surrounded with single quotes to protect it from HOOPS’ normal parsing, which converts everything to lower case (e.g. “font name = ‘Apple-Chancery’”).

Default is “extended font search”.

[no] fatal errors [= (option, option…) ]

[no] errors [= (option, option…) ]

[no] warnings [= (option, option…) ]

[no] info [= (option, option…) ]

These four options control whether Report_Error() should print out or skip messages of the given classes. They only control the error announcements made by the Report_Error() error handler. The system controls the rest of its normal error recovery. Valid choices for options include:

\li on/enable<br>All messages at the specified severity are on.
\li off/disable<br>All messages at the specified severity are off.
\li on/enable=(#/#,...)<br>One or more messages are turned on.
\li off/disable=(#/#,...)<br>One or more messages are turned off.
\li once=(#/#,...)<br>One or more messages will report only once.

A common use of these error-reporting options is to turn off messages temporarily. This is helpful in situations where you’re aware that what you’re doing might generate a warning. The code might look like this:

Show_System_Options (original_options)
Define_System_Options ("no warnings, no errors")
Delete_Segment ("might-be-gone-already-oh-dear")
Define_System_Options (original_options)

The #/# is the category and specific numbers of the message, as shown in the normal error report. So, for instance,

Define_System_Options("errors=(off,enable=(1/3,13/57),once=21/9")

…would turn all errors off, except that the errors represented by the number pairs (1,3) and (13,57) would still be reported, and the error (21,9) would only be reported the first time it might occur.

Note that the basic on/off settings override (discard) any individual settings that were previously set; moving the “off” to the end in the previous example would leave all errors off.

These setting only control the reporting of messages (calling any registered error handlers, HC_Report_Error by default). Any side effects of the message generation are unchanged - fatal messages still call exit handlers, and the messags id is recorded for Show_Error.

Use this feature judiciously. The default is to print everything.

[no] font directory = pathlist

This option specifies a comma separated list of directories where font information is stored. HOOPS searches each of the specified directories for font files that end with specific “known” suffixes when extended font search is on. Some font formats are understood directly by the HOOPS core and are usable on all drivers. Other formats are understood only by specific device drivers. To find out which fonts are available for a specific driver, use the Begin_Font_Search() routine.

Normally you will need to surround your directory list string with either single or double quotation marks to prevent HOOPS from interpreting any special characters within. The default is “no font directory”.

[no] free [= <function pointer>]

Note: this option is strictly intended for debugging purposes under the advisement of Tech Soft 3D support; it is not support for use in commercially distributed applications.

Directs all general memory frees to the provided function. If set, the user must also provide a function to allocate the memory through the malloc option. When using these interfaces, the very first call to HOOPS must be Define_System_Options and the option string must include settings for malloc and free. These memory settings are persistent through calls to Reset_System(). The default setting is “no free”.

[no] legacy mesh face numbering [= on | off ]

Enables the (deprecated) mesh face numbering scheme that was in place prior to HOOPS version 14. See Insert_Mesh for details.

[no] legacy text extent [= on | off ]

HOOPS/3dGS can add the width of an X to the bounding box returned from Compute_Text_Extent calls. This can help ensure that the returned bounding box extends beyond the width of the text string. The default behavior is “legacy text extent = off”. This option was introduced in HOOPS 16 and the behavior prior to HOOPS 16 was the equivalent of “legacy text extent = on”.

[no] license [= ]

The license is used to enable HOOPS operation.

If an invalid or expired license is set, your application will exit when 3DF attempts to start.
If you are using a time-bound evaluation license, the HOOPS/3dGS viewport will display a small piece of text indicating that it’s an evaluation license, along with the number of days remaining until expiration.
The license string must be included inside back-ticks as indicated above.

The default is “no license.”

[no] malloc [= <function pointer>]

Note: this option is strictly intended for debugging purposes under the advisement of Tech Soft 3D support; it is not support for use in commercially distributed applications.

Directs all general memory allocations to the provided function. If set, the user must also provide a function to free the memory through the free option. When using these interfaces, the very first call to HOOPS must be Define_System_Options and the option string must include settings for malloc and free. These memory settings are persistent through calls to Reset_System(). The default setting is “no malloc”.

[no] message limit [= (ddd) ]

HOOPS tries hard to be forgiving of error situations, and almost always is able to return control to the application program after printing its error messages. But one error often leads to another. “Message limit” is used to set a limit on the number of messages printed out before HOOPS calls it quits.

The “messages given” counter is incremented and checked in Report_Error() , and reset whenever Define_System_Options() is called on “message limit”. The default is “no message limit”.

[no] metafile directory = ‘pathlist’

This option specifies a comma separated list of directories where HOOPS metafiles are stored. HOOPS searches each of the specified directories for metafiles. When writing metafiles, the first directory in the list is used. The default is “no metafile

directory.”

[no] multi-threading [= off | full ]

Enables semaphores necessary to make 3dGS thread-safe. Performance penalty for this option is minimal. “full” renders each 3dGS call completely thread-safe. Depending on the function call, the block can be either a read or a read/write lock. At this point, database edits may occur during any draw update. “off” affords no thread protection. Default is “off”. As of Release 18, “basic” has been deprecated.

Warning: When using “multi-threading = full”, users should call HC_Reset_System right before their application’s main function exits to ensure all internal HOOPS threads have been safely shutdown.

[no] near limit update promotion [= on | off]

Controls whether changes to top-level bounding volumes can potentially promote incremental updates to full updates. In this case, “top level” means the level where the camera is defined. This option only comes into play when there is an automatically adjusting camera near limit (i.e. when Set_Camera_Near_Limit() is given a value less than or equal to zero, or not called at all).

Examples of changes that will cause full updates when using auto-adjusting near limits are as follows: (1) when geometry is added (but not removed); and (2) when any changes are made within segments that have the “quick moves=spriting” heuristic set.

The default is “near limit update promotion = on”.

[no] obsolete checking [= on | off ]

This is a special option available for generating warning messages when routines considered obsolete in HOOPS are called. The default is “no obsolete checking”.

[no] old style pathnames [= on | off ]

If this option is “on”, HOOPS calls such as Show_Selection_Pathname will return include segment pathnames in a way that is ambiguous, particularly in cases where a selection is instanced more than once. When “off”, include pathnames will indicate which segment in the path was the original include. This option is provided post-6.2-release to accommodate those programs which may directly parse the path string and so depend on the old behavior. The default is “off”. See the documentation of Show_Selection_Element for details on the pathname conventions.

populate memory limit [= (ddd)]

This option is sets how much memory HOOPS will use, in MB, before starting to eject the contents of populated segments. It will attempt to limit database memory use to approximately this value.

This option is currently only used by the OOC point cloud capabilities.

The default is 128.

[no] raw memory [= on | off]

Note: this option is strictly intended for debugging purposes under the advisement of Tech Soft 3D support; it is not support for use in commercially distributed applications.

Disables the memory cache that 3dGS uses for allocating and freeing small objects. Setting this can result in significant performance drops. The default setting is “no raw memory”.

[no] restrip on edit [= on | off ]

When on, this option causes tristrips to be automatically recalculated when a shell’s point list is edited. It should only be set if the change to the shell points array does not change the topology of the shell (which would include adding/removing points, or causing a shell face to go from concave to convex or vice versa). If the topology is changed and this option is set during the edit, then the correctness of the shell is not guaranteed. A synonym is “shell restrip on point edit”. Default is “restrip on edit”.

[no] sanity checking [= on | off ]

This is a dangerous option. It is available for turning off HOOPS checking of anomalies such as inclusions that cause a loop. This option can be deactivated to improve performance once applications are error free. The default is “sanity checking”.

[no] update control [= thread] = [on | off ]

Controls whether HOOPS will propagate redraw activity when modifications are made to the segment tree. If you set the optional “thread” value, then redraw activity will only be affected for modifications caused by that same calling thread. Please note that if you set “update control = off”, then your application will need to call Control_Update() to trigger updates. The default is “update control = on”.

[no] video memory limit [= (xxx) ]

Sets the limit of video memory to use, where xxx is a number that can be specified as “mb” for megabytes, “kb” for kilobytes, or with no units at all for bytes. Textures count towards the limit but are never suppressed. Display lists, on the other hand, are not created if they would put the total video memory usage over the specified limit. On the Windows platform, HOOPS automatically queries the capabilities of the system’s video card and sets the default video memory limit to be 32 MB less than what is available. For all other platforms, the default setting is “no video memory limit”.

\par NOTES

To prevent deadlock, error messages are automatically turned on for the duration of a call to Define_System_Options() .

The starting System Options can be changed on most operating systems by means of the environment variable “HOOPS_SYSTEM_OPTIONS”. This may be convenient, for example, for turning on “continuous update” or for turning messages off temporarily.

See also

HC_Control_Update, HC_Report_Error, HC_Define_Error_Handler, HC_Show_Bounding_Info, HC_Show_System_Options, HC_Show_Driver_Options.

Parameters: list – - A quoted string or a string variable containing a list of the desired option settings.

void HC_Define_Texture(char const *texture_name, char const *definition)

Assigns a name to a set of texture mapping options.

Texture mapping is a method of giving rendered surfaces high detail at minimal computational cost. For example, rather than inserting thousands of individually colored faces to simulate a wood-grain surface, a texture map could be used to “paint” an image of wood-grain onto a set of shell faces.

Supported Options:: caching, camera, decal, down sampling, layout, modulate, parameter offset, parameterization source, transform, transform override, tiling, source, source callback, source callback data, interpolation filter, decimation filter, red channel mapping, green channel mapping, blue channel mapping, alpha channel mapping, value scale,
DETAILS

Texture mapping works by linking every pixel of a face to a corresponding “texel” (texture element) of a HOOPS image (one of many possible texture sources). As a textured face is drawn, the referenced image texels are used to modulate one (or more) of the surface’s material properties. Defined texture names are used with the Set_Color() routine to assign textures to specific material properties.

The most common method of defining the connection between shell or mesh surface pixels and image texels is with a texture coordinate at each vertex (set by MSet_Vertex_Parameters() ). Other methods are described below.

The following diagram illustrates the stages involved when texturing, where each stage is a settable option of the texture definition.

../../_images/dt1.gif

The definition parameter to Define_Texture() is a comma-separated list of options which can include the following:

[no] caching

When set, 3dGS will do its best to reduce the memory impact of using textures. This may be of use for developers who are using large textures extensively.

default value: “no caching”

[no] camera = segment

This option allows you to specify which segment’s camera should be used for rendering a “skybox”. You can make a skybox by creating a cube texture and setting that as your window color via ::Set_Color as described in the HOOPS/3dGS Programming Guide entry on skyboxes and cube maps

.

default value: “no camera”

[no] decal

This setting is only relevant when the texture is applied to diffuse channel 0. When set, any transparent portions of the texture show the underlying diffuse color, rather than making the entire material transparent.

default value: “no decal”

[no] down-sampling

Instructs HOOPS not to down-sample images that exceed 512x512 pixels, but instead to try and create a texture as close as possible to the original size of the image, without exceeding the texture size limit on the graphics card. For textures, many graphics cards have a limit of between 512x512 and 4096x4096 pixels.

default value: “no downsampling”

layout = (unknown | rectilinear | spherical) [unknown]

Normal texturing assumes “rectilinear”, a simple0->1 mapping in x & y. Environment mapping assumes “spherical”, a sort of distorted polar coordinates, as defined by OpenGL for environment mapping. The default value, “unknown”, means the code can assume the layout is whatever is appropriate for the usage.

default value: “unknown”

[no] modulate

This setting is only relevant for diffuse channels. When set, the texture will modulate, rather than replace, materials that came before it (for diffuse channel n, this would be first the underlying surface color then all diffuse channels i < n.

Note that this explicit modulate setting is distinct from the implicit modulation set as part of the color, e.g. Set_Color (“red brick”), where “brick” is a previously defined texture. If “brick” were defined with modulation turned on, then Set_Color (“diffuse color = red, diffuse texture = brick”) would have the same visual effect.

default value: “no modulate”

parameter offset = x

Specifies how far into each vertex parameter list to skip before coming to the texture parameters for this specific texture. If the offset exceeds the number of parameters at each vertex, then 0 is assumed.

default value: “0”

parameterization source = source

In order to apply a texture to a surface, each pixel of the rendered surface must be “mapped” to a texel in the texture source. The “parameterization source” option allows you to specify which of the surface’s parameters will be used for the surface-pixel to image-texel mapping. Currently, the only valid choices for source are the following:

cylinder

Automatically creates the texture map based on a cylindrical mapping.

natural uv

Stretches the texture along meshes and NURBS surfaces according to their natural internal parameterization. For meshes this is range [0..1]. For NURBS surfaces this is range [0..(control point count - degree)]. Shells do not have a natural parameterization, so the [u,v] coordinates are generated according to the following formula: [u=x+z, v=x+y], where x, y, and z are object space coordinates.

object

The XYZ coordinates of the local geometry. Identical to world space except that this coordinate system is before modelling matrices are applied.

physical reflection

An alternative setting for environment mapping. When set, this calculates the environment coordinates as a reflection between the normal (to the item being textured) and the view vector. The result is that the environment map is not held at a fixed position.

reflection vector

This is the recommended setting for an environment map. It matches the behaviour of OpenGL environment mapping, in that the environment is held at a fixed position along the view vector.

surface normal

The surface normal computed for the local screen pixel.

sphere

Automatically creates the texture map based on a spherical mapping.

uv

Used for traditional image based texture maps. The parameterization source comes from a user supplied (u,v) coordinate set with the MSet_Vertex_Parameters() routine.

world

A three-valued parameter (XYZ) corresponding to the surface pixel’s 3D world coordinate position (the coordinate system of geometry after modelling matrices have been applied, but before projecting through a camera into a window). The Z value is ignored unless there is a texture matrix that has set.

Although these parameters are defined only at shell or mesh vertices, values are interpolated for all interior pixels.

For all parameterization sources, a 4 component vector is generated. Sources with fewer than 4 components are padded as follows:

\code{.txt}

one parameter (i) [i, 0, 0, 1] two parameter (i,j) [i, j, 0, 1]

Parameters

texture_name – The name this texture definition will be assigned to.
definition – A quoted string or a string variable containing a list of desired options for this specific texture.

void HC_Define_Local_Texture(char const *texture_name, char const *definition)

Define a texture on the currently open segment.

This function allows you to define a texture on a specific segment and which will then be inherited like any other attribute. Consequently the only geometry which will be able to use that texture definition is geometry that is either in that segment or contained in one of its child segments. Refer to Define_Texture() for all the possible options.

Supported Options:: caching, decal, down sampling, layout, modulate, parameter offset, parameterization source, transform, tiling, source, interpolation filter, decimation filter, red channel mapping, green channel mapping, blue channel mapping, alpha channel mapping, value scale,
DETAILS

Local textures differ from regular textures in that they are resolved at draw time. This can mean that users will be surprised that HOOPS warnings regarding textures may appear at a different stage during the update process.

NOTES

See also

HC_Define_Texture

Parameters

texture_name – - The name this texture definition will be assigned to.
definition – - A quoted string or a string variable containing a list of desired options for this specific texture.

Key HC_Define_Shader(char const *name, char const *options, char const *shader_source)

Defines a section of code that will be injected into HOOPS 3DF shaders.

There are two types of shaders that can be defined through this function call: legacy and modern. Legacy custom shaders can only be bound to the pixel shader. Modern custom shaders can be bound to both the vertex and pixel stages and allow users to define custom input and output fields as well as uniforms. This function will return a Key when used to define a modern custom shaders. All shader functions that require a Key are only valid with modern custom shaders and vice-versa. In order to define a modern custom shader the options field should just contain a string describing the stage of the pipeline where the shader will bind. Example: stage = pixel will create a legacy custom shader pixel will create a modern custom shader The main function in the source code of modern shader has to be called custom_main.

Supported Options:: multitexture, parameterization source, stage transform
DETAILS

The following paragraphs only apply to legacy custom shaders

With Define_Shader, you can specify a section of code to be injected into the pixel shader instead of replacing the entire shader. The shader source can be a snippet of glsl or hlsl code that has access to lights, textures, and coordinates to use as inputs, and can override or modify values for material relating to colors and local surface normals.

Note that if your shader code uses hlsl specific calls, the driver type for your model at render time must be DX11 while shaders that use glsl specific calls will only work with OpenGL2.

All shader definitions are considered local to the current segment and below.

The options parameter to Define_Shader is a comma-separated list of settings which can include the following:

[no] multitexture = on/off

If set, any diffuse textures present in channels greater than 0 will be layered on top of the material properties that are specified in the shader. Normally, all diffuse texture input is assumed to be handled in the shader while remaining textures would be skipped. The default value is “no multitexture”.

parameterization source = source

Like textures, shaders will require some form of parameterization source to be considered active. The possible settings are as described in the Define_Texture()’s description of parameterization source. The default value for this option is “world”.

stage = xxx

This option specifies where the shader code should be injected. Currently, “material” is the only acceptable value, but future versions, HOOPS may allow other stages of the pipeline to be overridden. The default value is, of course, “material”.

[no] transform = segment

The possible settings for this option are as described in the Define_Texture()’s description of transform.

This interface is used both for defining legacy custom shader and modern custom shaders introduced with v27. Modern custom shaders allow users to define custom input / outputs as well as uniforms and use a new hlsl/glsl interface to make writing custom shaders easier and more powerful.

NOTES

In order to define a modern custom shader, the option field must contain just ‘vertex’ or ‘pixel’ based on the stage of the graphics pipeline the custom shader will bind to. When defining a modern custom shader a Key to it is returned by this function. When defining a legacy custom shader this function will return -1.

Modern custom shader definitions can be deleted using Delete_By_Key.

See also

HC_Delete_By_Key, HC_Show_Shader_By_Key

Parameters

name – - A name to associate with the shader code.
options – - A quoted string or a string variable containing a list of the desired option settings.
shader_source – - A section of shader code that be injected into the HOOPS shader.

Returns

The key to the defined shader. This value is only valid when defining modern custom shaders.

void HC_Delete_By_Key(Key key)

Throws away a segment identified by key rather than by name, or throws away a particular geometry item.

If the given key refers to a segment - if it was returned from Open_Segment() or Create_Segment() - then, as with Delete_Segment() , that segment and all its subsegments are deleted from the segment tree. This is useful when the segment was originally created without a name (i.e., it was a “no-name” segment), or when it’s easier to keep track of the segment by key rather than name.

DETAILS

If the given key refers to a geometric primitive, such as a line or a polygon, that single primitive is deleted from the database and (at the next Update) from the screen. For comparison, Flush_Contents() deletes all the primitives from the specified segment. Delete_Segment() deletes the primitives and the segment structure itself.

Finally, if the given key was returned from Include_Segment() or Style_Segment() , that segment cross-reference is removed from the database - the “include” or “style” is no longer performed. The segments themselves remain unaffected.

NOTE

If the item is currently open ( Open_Segment() or Open_Geometry() ) an error will be reported and the deletion will fail.

See also

HC_Flush_Contents, HC_Delete_Segment, HC_Open_Segment, HC_Open_Geometry, HC_Create_Segment, HC_Include_Segment, HC_Style_Segment.

Parameters: key – - Key returned by a previously called routine.

void HC_Delete_Segment(char const *segment)

Throws away a segment when you no longer need it. Can also be used to shut down a display.

Deletes a previously created segment and all its subsegments from the segment tree. Nothing that’s to be deleted can be open. Segments referenced indirectly by the deleted segment (Styles and Includes) are not affected.

DETAILS

Closely related routines include Reset_System() , which quickly deletes the entire tree plus all color definitions, alias definitions, etc., Delete_By_Key() , which lets you select individual picture elements for removal; and Flush_Contents() , which deletes some or all of the contents of the segment but leaves the segment intact.

NOTE

If a segment being deleted is a “driver” segment - “?Picture”, or something you’ve explicitly given a Driver attribute - the action routine will be called to shut down the device.

See also

HC_Rename_Segment, HC_Flush_Contents, HC_Delete_By_Key, HC_Reset_System, HC_Set_Driver, HC_Open_Segment, HC_Close_Segment.

Parameters: segment – - Name of the segment(s) to be deleted. Can include wild cards.

void HC_Dolly_Camera(double right, double up, double in)

One of a set of routines to manipulate one’s point of view. “Dolly” moves the “camera” left and right, up and down, or in and out.

Once the point of view of your scene has been determined (with Set_Camera_Position() , Set_Camera_Target() , Set_Camera_By_Volume() , etc.) there are a number of ways to make adjustments. Dolly_Camera() (“dolly” is a motion picture industry term) trundles the camera in the direction you specify. The scene on the screen appears to move in the opposite direction. The distances to be moved can be negative. The camera’s target gets moved a matching distance, and the field-of-view remains unchanged.

DETAILS

Both Zoom_Camera() and Dolly_Camera() can be used to make what’s in front of the camera appear larger. If you want to “focus in” on something without changing the “place you’re standing”, use Zoom_Camera() rather than Dolly_Camera() . If you want to “walk around” the thing you’re looking at, and keep looking at it, use Orbit_Camera() . And if you want to look in a different direction, but not change where your feet are, use Pan_Camera() .

NOTE

If there is no Camera set up already in the segment, Dolly_Camera() will create a default camera (-1 to +1, etc.) and then dolly it. The owning segment’s camera is ignored, so it’s advisable to always do your camera work in the same segment.

See also

HC_Set_Camera or HC_Set_Camera_By_Volume, HC_Set_Camera_Field, HC_Set_Camera_Position, HC_Set_Camera_Projection, HC_Set_Camera_Target, HC_Set_Camera_Up_Vector, HC_Zoom_Camera, HC_Orbit_Camera, HC_Pan_Camera, HC_Roll_Camera, HC_Set_Window, HC_Translate_Object, HC_Rotate_Object.

Parameters

x_dir – - Distance to move the camera in the x-direction.
up – - Distance to raise the camera. (Negative numbers lower the camera.)
in – - Distance to move the camera into the scene. (Negative numbers back the camera away.)

intptr_t HC_Dump_Memory_Profile(char const *which)

void HC_Edit_Image(Key key, int xoffset, int yoffset, int xcount, int ycount, void const *data)

Modifies one, some, or all the pixel values in a previously-inserted image.

Edit_Image() lets the user modify a large image as it sits in the database. It is not necessary to delete or flush the segment and reinsert the image from scratch.

DETAILS

Edit_Image() operates on a rectangular sub-region of the original image, and replaces all the pixel values in that region with new ones. If the original image was specified “by reference”, and the system did not copy it, Edit_Image() modifies the actual original user memory locations.

If you have a key to an image, but do not know the format in which it was inserted (as when the user selects one of many images with the mouse), you can use Show_Image_Size() for the required information. It is not possible to change the size of an image except by starting over.

NOTES

See also

HC_Insert_Image, HC_Move_Image, HC_Show_Image, HC_Set_Color_Map, HC_Modify_Color_Map, HC_Delete_By_Key.

Parameters

key – - The numeric identifier returned by a previous call to Insert_Image() or Insert_Image_By_Ref() .
xoffset – - X offset, in pixels, from the upper-left corner of the original image at which to begin editing. The upper-left-most original pixel is numbered (0, 0). Values increase going right and going down.
yoffset – - Y offset, in pixels, from the upper-left corner of the original image at which to begin editing. The upper-left-most original pixel is numbered (0, 0). Values increase going right and going down.
xcount – - The number of columns of pixels to be changed, going down. The count, together with the offset, represents a rectangular change region within the original image.
ycount – - The number of number of rows of pixels to be changed, going to the right. The count, together with the offset, represent a rectangular change region within the original image.
data – - The new pixel values to be used, encoded in the same format as when the image was created. The first group of values in data is the upper-left-most of the change region; the next group is just to its right, etc. Passed by reference always.

void HC_Edit_Image_Options(Key image_key, char const *options)

Modifies the the options associated with a specific image.

The following choices are recognized for options. These are a subset of the options available when the image is initially inserted via a call to Insert_Image():

DETAILS

name = <string>

This name will be used to create a texture with the options specified in ‘texture options’. Providing no texture option string will mean that a texture is then created with default texture options.

[no] down-sample [= on | off]

If this is set, images will have a bilinear filter applied to them. This typically makes images look smoother, especially if zoomed upon. However, if there are hard edges (e.g. a checker board) it can make the image look unnecessarily blurry. Default = “down-sample”

size = ((float) width units, (float) height units) size = <float> units

Scale for an image where units is either “oru”, “sru” or “pixels”. “size = <float> units” will preserve aspect ratio.

[no] local [= on | off]

If set, the implicit texture created will be local to the currently open segment. Default = “no local”.

texture options = (…)

Options for the implicit texture created for the image. See Define_Texture() for the list of recognized options. The texture options will merge with any existing texture options.

See also

HC_Insert_Image, HC_Edit_Image, HC_Show_Image

Parameters

image_key – - The numeric identifier of an image, returned by a previous call to Insert_Image() or Insert_Image_By_Ref().
options – - Comma separated list of new options.

void HC_Edit_Mesh(Key key, int row_offset, int column_offset, int row_count, int column_count, Point const points[])

Modifies one, some, or all of the vertex values in a previously-inserted mesh.

Edit_Mesh() lets you modify a large mesh as it sits in the database. You don’t have to delete it or flush the segment and reinsert the mesh from scratch.

DETAILS

Edit_Mesh() operates on a rectangular sub-region of the original mesh, and replaces all the point values in that region with new ones.

It is not possible to change the size of a mesh except by starting over.

See also

HC_Insert_Mesh, HC_Edit_Shell_Points, HC_Flush_Contents, HC_Delete_By_Key.

Parameters

key – - The numeric identifier returned by a previous call to Insert_Mesh() .
row_offset – - Row offset from the origin of the original mesh at which to begin editing.
column_offset – - Column offset from the origin of the original mesh at which to begin editing.
row_count – - The number of rows of mesh data to be changed. The change area is between vertex ( row_offset, column_offset) and vertex ( row_offset + row_count- 1, column_offset + column_count - 1), inclusive.
column_count – - The number of columns of mesh data to be changed. The change area is between vertex ( row_offset, column_offset) and vertex ( row_offset + row_count - 1, column_offset + column_count- 1), inclusive.
points – - A [row_count x column_count] array of x-y-z triplets of the coordinates of the vertices of the mesh. You can also use a simple [row_count x column_count x 3] array of floats. A one-dimensional vector of floats (with the entries packed row by row) may be used in place of the full 2-D/3-D . Passed by reference always.

void HC_Edit_NURBS_Curve(Key key, int cp_offset, int knot_offset, int cp_count, int knot_count, Point const control_points[], float const weights[], float const knots[])

Modifies the control points, weights, and/or knots of a previously-inserted NURBS curve.

Edit_NURBS_Curve() lets you modify a NURBS curve as it sits in the database. In many circumstances, this function allows you to avoid deleting and reinserting the NURBS curve from scratch.

DETAILS

Edit_NURBS_Curve() replaces entries in the originally specified control_points, weights and/or knots (see Insert_NURBS_Curve()), starting at cp_offset for the control points and weights, and knot_offset for the knots. To retain the curve’s original values, simply pass NULL for that parameter.

cp_offset + cp_count must be less than the number of control points in the curve. knot_offset + knot_count must be less than the number of knots points in the curve (control points + order).

The system ignores the control_points and weights parameter if cp_count is equal to zero, and ignores the knots parameter if knot_count is equal to zero.

This function replaces, but does not add, values in the control point, weight and knot arrays. In other words, this function does not provide an interface to change the curve degree, control point count, or knot count. If any of those values need to be changed, the curve must be deleted and reinserted.

RESTRICTIONS

See also

HC_Insert_NURBS_Curve, HC_Show_NURBS_Curve, HC_Delete_By_Key, HC_Flush_Contents, HC_Flush_By_Key.

Parameters

key – - The numeric identifier returned by a previous call to Insert_NURBS_Curve() .
cp_offset – - Index of the control point and/or weight in the original NURBS curve definition at which to begin editing (indices start at 0).
knot_offset – - Index of the knot in the original NURBS curve definition at which to begin editing.
cp_count – - The number of control points and/or weights to replace.
knot_count – - The number of knots to replace.
control_points – - Vector of x-y-z triplets. (A simple N x 3 array may also be used. Passed by reference always. Can be NULL if not interested)
weights – - Control point weights. Passed by reference always. Can be NULL if not interested.
knots – - Knot sequence. Passed by reference always. Can be NULL if not interested.

void HC_Edit_Polygon(Key key, int offset, int ndelete, int insert, Point const points[])

Adjusts the boundary of a previously declared polygon.

Edit_Polygon() lets you modify a polygon with a long boundary as it sits in the database. You don’t have to delete and reinsert it from scratch.

DETAILS

Edit_Polygon() changes the originally specified points vector (see Insert_Polygon() ), starting at offset in the vector. First ndelete points are removed, then insert points, obtained from the points vector, are inserted.

If you delete point #1 and point #2 from a polygon, the next time around the point that was “#3” will now be #1. Insertion works in a similar manner.

NOTES

If you work in 3-D, make sure all the points are still coplanar. The system does not check for this and non-planar polygons result in undefined behavior.

If you originally specified the last point as your first point, the first point is considered redundant and trimmed off.

See also

HC_Translate_Object, HC_Delete_By_Key, HC_Flush_Contents, HC_Flush_By_Key, HC_Insert_Polygon, HC_Edit_Polyline.

RESTRICTIONS

Parameters

key – - The unique identifier returned by a previous call to Insert_Polygon() .
offset – - Number of the point in the original polygon definition just before which to start editing. “0” is the first. If specified as “-1”, editing starts after the last position.
ndelete – - Number of points to delete.
insert – - The number of points contained in points.
points – - Vector of x-y-z triplets to insert. (A simple N x 3 array may also be used.) Passed by reference always.

void HC_Edit_Polyline(Key key, int offset, int ndelete, int insert, Point const points[])

Adjusts the contents of a previously declared polyline.

Edit_Polyline() lets you modify a polyline with a long boundary as it sits in the database. You don’t have to delete or flush the segment and reinsert the polyline from scratch.

DETAILS

Edit_Polyline() deletes, inserts, and replaces entries in the originally specified points vector (see Insert_Polyline() ), starting at offset. The ndelete is done first, then the insert. The effect of a “replace” operation can be gained by deleting the same number of points you’re inserting.

The system ignores the points parameter if insert is equal to zero. In most languages, you still have to provide some sort of dummy array.

If the offset is specified as “-1”, the “far end”, any ndelete quantity is counted from the end of the list instead of the beginning.

If you insert or delete in the middle of the polyline, the offsets to points farther out on the polyline will be different next time.

Before HOOPS Version 2.0, the offset of the first point was (incorrectly) one, not zero.

NOTE

A polyline that was generated by inking can be edited similar to other polylines.

See also

HC_Translate_Object, HC_Delete_By_Key, HC_Flush_Contents, HC_Flush_By_Key, HC_Insert_Polyline, HC_Insert_Ink, HC_Restart_Ink, HC_Edit_Polygon.

Parameters

key – - The numeric identifier returned by a previous call to Insert_Polyline() .
offset – - Entry number in original polyline definition just before which to begin editing. “0” is the first. If specified as “-1”, editing starts after the last position.
ndelete – - Number of points to delete.
insert – - The number of points contained in points.
points – - Vector of x-y-z triplets to insert/append/prepend. (A simple N x 3 array may also be used.) Passed by reference always.

void HC_Edit_Shell_Faces(Key key, int offset, int ndelete, int ilist_length, int const insert_list[])

Creates or deletes faces in a previously declared shell.

Edit_Shell_Faces() lets you modify a complex shell as it sits in the database. You don’t have to delete and reinsert the shell from scratch.

DETAILS

Edit_Shell_Faces() changes the originally specified face_list (see Insert_Shell() ), starting at offset in terms of the number of whole faces.

First, if ndelete is non-zero then ndelete faces are dissolved from offset through offset+ ndelete - 1. The points referenced by those faces still exist; the face attributes (see Open_Face() ) are lost. If that face was the last to reference an edge, then the edge is dissolved and its attributes (see Open_Edge() ) are also lost.

If ilist_length is non-zero, new faces are then constructed using the information in insert_list, to a maximum of ilist_length. The new faces are inserted in the list just before offset.

Finally, the offsets of the faces are renumbered to reflect any changes.

See also

HC_Edit_Shell_Points, HC_Edit_Mesh, HC_Show_Shell, HC_Delete_Segment, HC_Delete_By_Key, HC_Flush_Contents, HC_Flush_By_Key, HC_Insert_Shell.

Parameters

key – - The unique identifier returned by a previous call to Insert_Shell() .
offset – - Number of the face in the original shell definition before which to start inserting or at which to begin deleting. “0” is the first. If specified as “-1”, editing starts after the old final face.
ndelete – - Number of faces to delete.
ilist_length – - Number of integers in insert_list.
insert_list – - Encoded description of how to connect the existing vertices to build new faces for the shell. See Insert_Shell() for format.

void HC_Edit_Shell_Points(Key key, int offset, int ndelete, int insert, Point const points[])

Changes or deletes vertex points of a previously declared shell, or adds new points.

Edit_Shell_Points() lets you build a complex shell as it sits in the database. You don’t have to delete and reinsert the shell from scratch. Edit_Shell_Points() provides this function for the points part of the original definition. A sister routine, Edit_Shell_Faces() , lets you change the face_list part of the original definition.

DETAILS

Edit_Shell_Points() changes the originally specified points vector (see Insert_Shell() ), starting at offset in the vector.

If ndelete is equal to insert and non-zero, that number of points are modified in place. The face connections and attributes of the points remain unchanged. Their x-y-z values are updated from the new points array.

If ndelete is non-zero (and not equal to insert) that number of points from the original list are discarded. The faces that referenced those points are dissolved and no longer exist. The face_list (see Show_Shell() ) is updated appropriately.

If insert is non-zero (and not equal to ndelete) that number of points from the new points vector are copied into the shell point list. The newly inserted points are not connected to any faces until you make an appropriate call to Edit_Shell_Faces() .

Finally, the points are renumbered to reflect any changes. The stored face_list (see Insert_Shell() ) will show the changed numbering.

See also

HC_Edit_Shell_Faces, HC_Edit_Mesh, HC_Set_Modelling_Matrix, HC_Show_Shell, HC_Delete_Segment, HC_Delete_By_Key, HC_Flush_Contents, HC_Flush_By_Key, HC_Insert_Shell.

Parameters

key – - The unique identifier returned by a previous call to Insert_Shell() .
offset – - Number of the point in the original shell definition just before which to start editing. “0” is the first. If specified as “-1”, editing starts after the old final point.
ndelete – - Number of points to delete.
insert – - The number of points to be inserted.
points – - Vector of x-y-z triplets to insert. (A simple N x 3 array may also be used.) Passed by reference always.

void HC_Edit_Text(Key key, int row, int column, int erase, int ndelete, char const *new_text)

Manipulate the characters in a previously defined string.

If you just want to put up and remove messages use simple segments, either create and delete them or just flush them out. But if your text is long and complicated, Edit_Text() may be of value to facilitate incremental changes.

DETAILS

The three possible operations - erase, delete, and insert new_text - are performed consecutively in that order. Note, specifying a -1 for ndelete gives the effect of a “replace” operation, without having to count the characters yourself.

If key resulted from a call to Insert_Text_With_Encoding() , then the “encoding” of new_text is assumed to be the same as that of the original text. If in doubt, use Show_Text_Encoding() first.

If the number of characters inserted does not equal the number deleted, the overall length of the stored text will be changed. Text alignment will be recomputed as needed.

See also

HC_Flush_Contents, HC_Flush_By_Key, HC_Insert_Text, HC_Set_Text_Alignment, HC_Set_Text_Font, HC_Scroll_Text, HC_Show_Text_Encoding, HC_Compute_Text_From_Text16.

Parameters

key – - The identifier returned by a previous Insert_Text() or Insert_Text_With_Encoding() .
row – - The row of text that the Edit operates within. This should be always specified as zero.
column – - The character position within the row where the Edit should start. The leftmost character in any row is at position zero.
erase – - The number of characters to change to blanks.
ndelete – - The number of characters to remove from this row. If spec ified as “-1”, the number deleted will be equal to length of new_text inserted.
new_text –
- Characters to be inserted (if any).

void HC_Edit_Text_Leader(Key key, double x, double y, double z, char const *options)

void HC_End_Alias_Search(void)

Terminates the alias search sequence and frees any involved memory.

See also

HC_Begin_Alias_Search()

void HC_End_Callback_Name_Search(void)

Terminates the callback name search sequence and frees any involved memory.

See also

HC_Begin_Callback_Name_Search()

void HC_End_Color_Name_Search(void)

Terminates the color name search sequence and frees any involved memory.

See also

HC_Begin_Color_Name_Search()

void HC_End_Contents_Search(void)

Terminates the object search sequence and frees any involved memory.

See also

HC_Begin_Contents_Search()

void HC_End_Font_Search(void)

Terminates the font search sequence and frees any involved memory.

See also

HC_Begin_Font_Search()

void HC_End_Open_Segment_Search(void)

Terminates the segment search sequence and frees any involved memory.

See also

HC_Begin_Open_Segment_Search()

void HC_End_Segment_Search(void)

Terminates the segment search sequence and frees any involved memory.

See also

HC_Begin_Segment_Search()

void HC_End_Texture_Search(void)

Terminates the texture search sequence and frees any involved memory.

See also

HC_Begin_Texture_Search()

void HC_End_Shader_Search(void)

Terminates the shader search sequence and frees any involved memory.

See also

HC_Begin_Shader_Search().

void HC_End_Glyph_Search(void)

Terminates the glyph search sequence and frees any involved memory.

See also

HC_Begin_Glyph_Search()

void HC_End_Line_Style_Search(void)

Terminates the line style search sequence and frees any involved memory.

See also

HC_Begin_Line_Style_Search()

DETAILS

void HC_End_Shape_Search(void)

void HC_Exit_Program(void)

Calls the defined exit handlers, and exits to the operating system with a normal status.

Provides an orderly way for you to terminate execution. HOOPS will try to call this routine when your program terminates, but some compilers and operating systems might not support this ability, so you may want to call it yourself.

DETAILS

The currently defined exit handlers are called. These usually include Reset_System() , which shuts down devices and frees memory. The operating system is then called with a “normal” exit status to terminate program execution.

See also

HC_Abort_Program, HC_Define_Exit_Handler, HC_Reset_System.

bool HC_Find_Alias(char *alias)

Retrieves the alias names, one at a time. The function returns false when all aliases have been returned.

See also

HC_Begin_Alias_Search()

Parameters: alias – - One alias name. Returned to user. Passed by reference always.
Returns: flag

bool HC_Find_Callback_Name(char *name)

Retrieves the callback names, one at a time. The function returns false when all aliases have been returned.

See also

HC_Begin_Callback_Name_Search()

Parameters: name – - Name of callback routine found in the system’s list.
Returns: flag

bool HC_Find_Color_Name(char *name, char *er_name, char *ish_name)

Retrieves the color names, one at a time. The function returns false when all color names have been returned.

See also

HC_Begin_Color_Name_Search()

Parameters

name – - Simple name from the list of definitions. Returned to user. Passed by reference always.
er_name – - The “er” (1st degree) combining form (if any) of the name above. Returned to user. Passed by reference always.
ish_name – - The “ish” (2nd degree) combining form (if any). Returned to user. Passed by reference always.

Returns

flag

bool HC_Find_Contents(char *type, Key *key)

Retrieves the object keys, one at a time. The function returns false when all objects have been returned.

See also

HC_Begin_Contents_Search()

Parameters

type – - The type of object found by this call. Returned to user. Passed by reference always.
key – - Unique numeric identifier for this object. For attribute types it will be the key of the segment owning the attribute. Returned to user. Passed by reference always.

Returns

The function returns false when all objects have been returned.

bool HC_Find_Contents_Original_Key(char *type, Key *key)

If keys have been renumbered, this function retrieves the original object keys, one at a time. The function returns false when all objects have been returned.

See also

HC_Begin_Contents_Search()

DETAILS: This function returns the original key value for the item, which is safe to use regardless of which segment is open because, unlike locally renumbered keys, it is unambiguous and not dependent on context.

Parameters

type – - The type of object found by this call. Returned to user. Passed by reference always.
key – - Unique numeric identifier for this object. For attribute types it will be the key of the segment owning the attribute. Returned to user. Passed by reference always.

Returns

The function returns false when all objects have been returned.

bool HC_Find_Font(char *name)

Retrieves the font names, one at a time. The function returns false when all aliases have been returned.

See also

HC_Begin_Font_Search()

Parameters: name – - The nameof one available font. Returned to user. Passed by reference always.
Returns: flag

bool HC_Find_Open_Segment(char *segment)

Retrieves the segments, one at a time. The function returns false when all segments have been returned.

See also

HC_Begin_Open_Segment_Search()

Parameters: segment – - Pathname of an open segment. Returned to user. Passed by reference always.
Returns: flag

bool HC_Find_Related_Selection(void)

Allows you to inspect the “next best” geometry item with the current Selection Event.

One mouse action (button-down, for example) generates at most one selection event. However, more than one geometry item can lie under or near the mouse.

DETAILS

The “Show Selection” routines that inspect a selection event normally return information about the best item of geometry that was selected. “Best” is defined as the selectable item nearest the mouse. If more than one geometry is right under the mouse, then it’s the one closest to the camera. Find_Related_Selection() , each time it is called, lets you inspect the next best item. The previous item information is discarded. When nothing more is available the entire Selection Event is discarded and Find_Related_Selection() returns false.

It is not necessary to look at all the related selections - you might only be interested in the best selection or the first few selections. Anything that causes the current event to be discarded ( Await_Event() , Get_Selection() , etc.) gets rid of the remaining uninspected related selections.

A typical C programming sequence that acquires a selection and does something with every one of the selected items would be the following:

HC_Get_Selection(...);
do {
    HC_Show_Selection_Pathname (...);
    HC_Show_Selection</a>_Element (...);
    // ... process item...
}
while (HC_Find_Related_Selection());

“Related” selections are only interesting if geometry testing is turned on. In the current implementation, at most one window will be included in the selection event, even if other windows are nearby and even if the included window is transparent. The window itself (if window selectability is on) will be last in the list of related selections.

NOTES

Use the “related selection limit” Heuristic and/or the “selection proximity” Driver Option judiciously to limit the amount of related-selection work the system has to do.

See also

HC_Enable_Selection_Events, HC_Compute_Selection, HC_Set_Selectability, HC_Set_Visibility.

Returns: success

bool HC_Find_Segment(char *segment)

Retrieves the segment names, one at a time. The function returns false when all segments have been returned.

See also

HC_Begin_Segment_Search()

Parameters: segment – - The full pathname of a segment that satisfies the search specification (segspec). Returned to user. Passed by reference always.
Returns: flag

bool HC_Find_Texture(char *name)

Retrieves the texture names, one at a time. The function returns false when all textures have been returned.

See also

HC_Begin_Texture_Search()

Parameters: name – - Simple name from the list of definitions. Returned to user. Passed by reference always.
Returns: flag

bool HC_Find_Shader(char *sname, Key *skey)

Retrieves the shader names, one at a time. The function returns false when all shaders have been returned.

See also

HC_Begin_Shader_Search().

Parameters

sname – - One shader name. Returned to user. Passed by reference always. Valid when searching for both a legacy or a modern shader.
skey – - One shader key. Returned to user. Passed by reference always. Only valid when searching for a modern shader. The most recently defined shader will be returned first, subsequent calls will return the following most recently defined shaders.

Returns

True or false. The function returns false when all shaders have been returned.

bool HC_Find_Glyph(char *name)

Retrieves the glyph names, one at a time. The function returns false when all glyphs have been returned.

See also

HC_Begin_Glyph_Search()

Parameters: name – - Simple name from the list of definitions. Returned to user. Passed by reference always.
Returns: flag

bool HC_Find_Line_Style(char *name)

Retrieves the line style names, one at a time. The function returns false when all line styles have been returned.

See also

HC_Begin_Line_Style_Search()

Parameters: name – - Simple name from the list of definitions. Returned to user. Passed by reference always.
Returns: flag

bool HC_Find_Shape(char *name)

void HC_Flush_Attributes(char const *segment)

Flushes attributes from a segment but leaves styles, geometry, segments, and subsegments.

See also

HC_Flush_Contents

DETAILS: Identical to Flush_Contents() (segment, “attributes”)

Parameters: segment – - Segment(s) to be flushed. Can contain wildcards.

void HC_Flush_By_Key(Key key)

Throws away the contents of a geometric primitive or a segment but leaves the structure intact.

If key refers to a polyline, polygon, or shell, all the points (and all of the faces) within the primitive are removed. New points, if desired, can be added with Edit_Polyline() , Edit_Polygon() , or Edit_Shell_Faces() .

DETAILS

If key refers to text, all the characters are removed. New characters can be added with Edit_Text() or via user input with Enable_String_Events() .

Flush_By_Key() is a quick method of making sure all the contents of a piece of geometry are gone. The “Edit” routines take more work and only remove some of the contents.

Lastly, if key refers to a segment, this call becomes a call to Flush_Geometry() on the segment. If the key refers to a Style or an Include, nothing happens.

See also

HC_Flush_Contents, HC_Delete_By_Key, HC_Edit_Polygon, HC_Edit_Polyline, HC_Edit_Shell_Faces, HC_Edit_Text.

Parameters: key – - Key returned by a previously called routine.

void HC_Flush_Contents(char const *segment, char const *filter)

Empties some or all of the drawing primitives, attributes, or subsegments from a segment.

The specified contents of the specified segment(s) are removed. The subsegments, if any, are not touched (unless you included the subsegments as part of the “contents to be removed”). The segment still exists under the same name. Flush_Contents() is often used when picture information comes and goes and is different each time. The structure of the segment tree should remain the same. Unlike the delete routines, the flush routines make no complaint if the item isn’t found and there’s no work to do. Flush_Contents() is a good way of getting rid of geometry and attributes and restoring a segment to a known state quickly.

DETAILS

Filter

is formatted exactly as in Begin_Contents_Search(). In other words, it is a list of the form “type, type,

…”, where each type can be any of the things that Begin_Contents_Search() would accept.

It’s also possible to flush a specific subset of attributes. For example, calling Flush_Contents(mySegment, “visibility =

lines”) will flush visibility attributes on line geometry types while maintaining the visibility attributes for other geometry types. This applies not only to visibility but to all other attributes as well; for example, you could flush “color = faces” to only flush color attributes applied to faces.

In addition, you can specify “no” in front of any of the above types. For example: “everything, no geometry, no windows, no

colormaps”, which flushes all types

except windows, colormaps, and all types of geometry. If specifications overlap (as in “geometry, no lines”), the last specification wins.

The plural “s” after each type is optional. The types can be in any combination of uppercase and lowercase. Leading and trailing blanks are not significant. A blank string is equivalent to “everything”.

An example of the use of Flush_Contents() is a message line on the screen. Each time you need a new message you can create a segment that contains the message plus the text spacing, text font, window, etc. Or you can leave a permanent segment that holds those attributes. Then you can create and delete a subsegment that has the actual text. Or skip the subsegment and put everything in one segment. Then flush out the text geometry when you’re done.

All three methods do work; it’s a matter of personal taste which you use.

To flush a whole tree, use the “…” segment wildcard. For example, to remove all the geometry in the tree rooted at “foo” (within the currently-open segment) you would say Flush_Geometry(“foo/…”).

NOTES

The system knows when a segment does not contain information that actually contributes something visible on the screen - it touches such a segment only briefly during display. So feel free to leave “flushed” segments laying around if this helps your program structure.

There is no ” Flush_Contents_By_Key() ” provided. If you want to get the same effect, use Flush_By_Key() (which just does geometry) or do an Open_Segment_By_Key() , a Flush_Contents() on “.”, and a close segment. (The Open_Segment_By_Key() and the “.” are quite efficient.)

Filter has almost the same meaning as in Begin_Contents_Search() , so a call to Flush_Contents() is similar to conducting a contents search and a Delete_By_Key() on each item found. The main difference is that attributes don’t have keys, so deleting them would be complicated.

Shells and Meshes can be opened and have their “hardware resources” flushed, but all other types of geometry (e.g. lines, polylines polycylinders and images) must have their “hardware resources” flushed from either their owning segment or some segment above. If the hardware resources are flushed, all resources used for things like display lists, vertex arrays and textures will be freed from the video card cache. Any of these resources that are needed to draw the scene will be regenerated on the next update.

See also

HC_Begin_Contents_Search, HC_Clear_Display, HC_Close_Segment, HC_Delete_Segment, HC_Open_Segment, HC_Open_Geometry, HC_Rename_Segment, HC_Reset_System.

Parameters

segment – - Segment(s) to be flushed. Can contain wildcards.
filter – - List of the types of objects you want to delete.

void HC_Flush_Geometry(char const *segment)

Flushes just geometry from a segment but leaves attributes, styles, segments, and subsegments.

See also

HC_Flush_Contents

DETAILS: Identical to Flush_Contents() (segment, “geometry”).

Parameters: segment – - Segment(s) to be flushed. Can contain wildcards.

void HC_Edit_Sphere(Key key, Point const *center, double radius, Vector const *axis, Vector const *ortho)

Edits a sphere object as it sits in the database without deleting and re-inserting.

The sphere primitive is tesselated at draw time which can greatly reduce the memory footprint of an application in which spheres are widely used. The tesselation of the sphere is controlled by the “sphere” option within the “tesselation” Rendering_Option.

DETAILS

See also

HC_Insert_Circle, HC_Insert_Ellipse, HC_Insert_Circular_Arc, HC_Insert_Circular_Chord, HC_Insert_Circular_Wedge, HC_Insert_Elliptical_Arc, HC_Insert_Polygon, HC_Set_Visibility, HC_Set_Edge_Pattern, HC_Set_Edge_Weight, HC_Set_Face_Pattern, HC_Set_Color, HC_Renumber_Key.

Parameters

key – - Key to a sphere object.
center – - An x-y-z triplet for the coordinates of center the sphere. (A simple array of three elements may also be used in most languages.) Passed by reference always.
radius – - Length of the radius of the sphere.
axis – - Vector that points in the longtitudal/vertical direction. If null then a default value of <0,10,0> is applied.
ortho – - Vector that points in the latitudal/horizontal direction. If null then a default value of <1,0,0> is applied.

void HC_Edit_Circle(Key key, Point const *point1, Point const *point2, Point const *point3)

Generates a flat, infinitely thin, colored-in circular object.

Edit_Circle() lets you modify a circle as it sits in the database. You don’t have to delete and reinsert it from scratch.

DETAILS

HOOPS uses a more compact structure to store a 2d circles (a circle with z=0 for start, middle and end). If and when such 2d circles are edited, all z values passed in for the start, middle and end points must be 0. In other words, if you need to make a 2d circle into a 3d circle, you have to delete and reinsert.

NOTES

See also

HC_Insert_Ellipse, HC_Insert_Circular_Arc, HC_Insert_Circular_Chord, HC_Insert_Circular_Wedge, HC_Insert_Elliptical_Arc, HC_Insert_Polygon, HC_Set_Visibility, HC_Set_Edge_Pattern, HC_Set_Edge_Weight, HC_Set_Face_Pattern, HC_Set_Color, HC_Renumber_Key.

Parameters

key – - key to a circle object.
point1 – - An x-y-z triplet for the coordinates of one of three on the circumference of the circle. (A simple array of three elements may also be used in most languages.) Passed by reference always.
point2 – - As above.
point3 – - As above.

void HC_Edit_Circle_By_Radius(Key key, Point const *center, double radius, Vector const *vector)

Generates a flat, infinitely thin, colored-in circular object.

Edit_Circle_By_Radius() lets you modify a circle as it sits in the database. You don’t have to delete and reinsert it from scratch.

DETAILS

HOOPS uses a more compact structure to store a 2d circles (a circle with z=0 for start, middle and end). If and when such 2d circles are edited, all z values passed in for the start, middle and end points must be 0. In other words, if you need to make a 2d circle into a 3d circle, you have to delete and reinsert.

NOTES

See also

HC_Insert_Ellipse, HC_Insert_Circular_Arc, HC_Insert_Circular_Chord, HC_Insert_Circular_Wedge, HC_Insert_Elliptical_Arc, HC_Insert_Polygon, HC_Set_Visibility, HC_Set_Edge_Pattern, HC_Set_Edge_Weight, HC_Set_Face_Pattern, HC_Set_Color, HC_Renumber_Key.

Parameters

key – - key to a circle object.
center – - An x-y-z triplet for the coordinates of one of three on the circumference of the circle. (A simple array of three elements may also be used in most languages.) Passed by reference always.
radius – - Length of the radius of the circle.
vector – - Vector that is perpendicular to the plane of the circle.

void HC_Edit_Circular_Arc(Key key, Point const *point1, Point const *point2, Point const *point3)

Modifies a circular arc as it sits in the database.

A portion of the circumference of a circle is added to the current segment. The order of the specified points is important. Specifically, the arc begins at the first point, is drawn through the second point and continues through the third point.

DETAILS

Circular arcs are grouped with lines, polylines, and elliptical arcs for rendering purposes. The rendition of an arc can be altered through the use of Line Color, Line Weight, and Line Pattern. An arc’s Visibility and Selectability can be controlled by the “line” or “polyline” keywords.

If you only work in two dimensions, specify all the z coordinates as zero. The system will automatically take note.

NOTES

Make sure the points are not colinear. The system checks and issues an error message if all three points lie on a line, or if two points are coincident.

See also

HC_Insert_Circular_Arc, HC_Edit_Circle, HC_Insert_Ellipse, HC_Insert_Elliptical_Arc, HC_Insert_Polyline, HC_Set_Visibility, HC_Set_Line_Pattern, HC_Set_Line_Weight, HC_Set_Color, HC_Renumber_Key.

Parameters

key – - key to a circcular arc.
point1 – - An x-y-z triplet for the coordinates of one of three ordered on the circumference of the circle. (A simple of three elements may also be used in most languages.) Passed by reference always.
point2 – - As above.
point3 – - As above.

void HC_Edit_Circular_Chord(Key key, Point const *point1, Point const *point2, Point const *point3)

Edits a circular chord as it sits in the database.

The order of the specified points is important. Specifically, the chord begins at the first point, is drawn through the second point and continues through the third point. A line connects the first and third points. The chord is defined as the area bounded by the points.

DETAILS

Circular chords are grouped with ellipses, polygons, shells and meshes for rendering purposes. The rendition of the interior of the chord can be adjusted with changes to Face Color and Face Pattern. The circumference of a chord can be made distinct from the interior through the use of Edge Color, Edge Pattern and Edge Weight. A chord’s Visibility and Selectability are controlled by the “edge”, “face”, and “polygon” keywords.

See also

HC_Insert_Circular_Chord, HC_Edit_Circle, HC_Insert_Circular_Arc, HC_Insert_Circular_Wedge, HC_Insert_Polygon, HC_Set_Visibility, HC_Set_Edge_Pattern, HC_Set_Edge_Weight, HC_Set_Face_Pattern, HC_Set_Color, HC_Renumber_Key.

Parameters

key – - key to a circle object.
point1 – - An x-y-z triplet for the coordinates of one of three ordered on the circumference of the circle.(A simple of three elements may also be used in most languages.) Passed by reference always.
point2 – - As above.
point3 – - As above.

void HC_Edit_Circular_Wedge(Key key, Point const *point1, Point const *point2, Point const *point3)

Edits a circular wedge as it sits in the database.

Circular wedges are grouped with ellipses, polygons, shells and meshes for rendering purposes. The rendition of the interior of the wedge can be adjusted with changes to Face Color and Face Pattern. The circumference of a wedge can be made distinct from the interior through the use of Edge Color, Edge Pattern and Edge Weight. A chord’s Visibility and Selectability are controlled by the “edge”, “face”, and “polygon” keywords.

DETAILS

The order of the specified points is important. Specifically, the wedge begins at the first point, is drawn through the second point and continues through the third point. The center of a circle defined by the 3 points is computed. Lines are drawn from the first point to the center and from the third point to the center. The wedge is defined as the area bounded by the points.

See also

HC_Insert_Circular_Wedge, HC_Insert_Circular_Arc, HC_Insert_Circular_Chord, HC_Insert_Polygon, HC_Set_Visibility, HC_Set_Edge_Pattern, HC_Set_Edge_Weight, HC_Set_Face_Pattern, HC_Set_Color, HC_Renumber_Key.

Parameters

key – - Key to a circular wedge.
point1 – - An x-y-z triplet for the coordinates of one of three ordered on the circumference of the circle.(A simple of three elements may also be used in most languages.) Passed by reference always.
point2 – - As above.
point3 – - As above.

void HC_Edit_Cutting_Plane(Key key, double a, double b, double c, double d)

Modifies a cutting plane as it exists in the database.

3D objects can be hard to comprehend when depicted on a 2D computer screen. One of the techniques to aid understanding is to slice the object open. A “Cutting Plane”, when inserted with other geometry in a HOOPS scene, basically causes all the geometry on the “open” side of the plane to vanish.

DETAILS

A HOOPS “scene” is the segment tree and all the geometry within a single HOOPS window. Cutting planes can be anywhere in the segment tree - they will still apply to the whole scene (with the exceptions noted below.) This allows the cutting plane to have its own attribute context - most importantly, segment name and current Modelling Matrix. It is the same rule that light sources follow in HOOPS.

Planes have two sides. If you consider the (a, b, c) part of the plane equation as a vector pointing out of the plane, that vector is normal to the plane and is, by convention, pointing out into the open cut-away territory. The side of the plane “behind” the normal vector is, by convention, the part of the scene retained by the cutting action.

There can be as many cutting planes as you want in a scene. There might be some limit as to how many planes can be handled in the hardware before the system has to switch to software mode. See the “hardware cutting planes” in Show_Device_Info() for details. Cutting planes have no effect on each other - other geometry is removed if it is cut away by any plane.

There are a few exceptions to the cutting action. First, lights are completely exempted - they are never cut away. Second, if “cutting plane” visibility is “off” for the branch of the segment tree in which the cutting plane is located, the cutting plane is turned off completely. Finally, if “cutting plane” visibility is “off” for a branch of the tree in which regular geometry is located, that geometry will not “receive” cutting planes: it will be exempted from being cut. This permits a partial cut-away to be drawn.

Cutting planes slow drawing down a little.

NOTES

Cutting planes do not act within a marker symbol, a wide line, or a single text character (unless the text is fully-transformable.)

On some devices setting the “no clipping” Heuristic may have the side effect of disabling cutting planes.

Cutting planes cannot be scaled by 0.

RESTRICTIONS

See also

HC_Insert_Cutting_Plane, HC_Show_Device_Info, HC_Set_Visibility, HC_Set_Heuristics, HC_Insert_Polygon, HC_Insert_Shell, HC_Insert_Mesh.

Parameters

key – Key to a cutting plane object.
a – - The parameters of an equation of the form ax + by + cz + d = 0, defining a plane.
b – - As above.
c – - As above.
d – - As above.

void HC_Edit_Ellipse(Key key, Point const *center, Point const *major, Point const *minor)

Edits an ellipse as it sits in the database.

Ellipses are grouped with circles, polygons, shells, and meshes for rendering purposes. The rendition of the interior of the ellipse can be adjusted with changes to Face Color and Face Pattern. The circumference of an ellipse can be made distinct from the interior through the use of Edge Color, Edge Pattern and Edge Weight. An ellipse’s Visibility and Selectability are controlled by the “edge”, “face”, and “polygon” keywords.

DETAILS

If you only work in two dimensions, specify all the z coordinates as zero. The system will automatically take note.

NOTES

Make sure the points are not colinear. The system checks and issues an error message if all three points lie on a line, or if two are coincident.

See also

HC_Insert_Ellipse, HC_Insert_Circle, HC_Insert_Circular_Arc, HC_Insert_Elliptical_Arc, HC_Insert_Polygon, HC_Set_Visibility, HC_Set_Edge_Pattern, HC_Set_Edge_Weight, HC_Set_Face_Pattern, HC_Set_Color, HC_Renumber_Key.

Parameters

key – Key to an ellipse object.
center – - An x-y-z triplet for the coordinates of the center of the ellipse. (A simple array of three elements may also be used in most languages.) Passed by reference always.
major – - An x-y-z triplet for the coordinates of the intersection of the ellipse and its major axis. Passed by reference always.
minor – - An x-y-z triplet for the coordinates of the intersection of the ellipse and its minor axis. Passed by reference always.

void HC_Edit_Elliptical_Arc(Key key, Point const *center, Point const *major, Point const *minor, double start, double end)

Edits an elliptical arc as it sits in the database.

Elliptical arcs are grouped with lines, polylines, and circular arcs for rendering purposes. The rendition of an arc can be altered through the use of Line Color, Line Weight and Line Pattern. An ellipse’s Visibility and Selectability can be controlled by the “line” or “polyline” keywords.

DETAILS

The direction of the perimeter is determined by the shortest path between the points used to define the major and minor axes. The starting and ending points are the parametric angular distances, specified between 0.0 and 1.0, along the perimeter. For example, a quarter of an ellipse could be specified with start and end points of 0.25 and 0.5, respectively.

If you only work in two dimensions, specify all the z coordinates as zero. The system will automatically take note.

NOTES

Make sure the points are not colinear. The system checks and issues an error message if all three points lie on a line, or if two points are coincident.

See also

HC_Insert_Elliptical_Arc, HC_Insert_Ellipse, HC_Insert_Circle, HC_Insert_Circular_Arc, HC_Insert_Polyline, HC_Set_Line_Pattern, HC_Set_Line_Weight, HC_Set_Color, HC_Renumber_Key.

Parameters

key – - Key to an elliptical arc object.
center – - An x-y-z triplet for the coordinates of the center of an ellipse. (A simple array of three elements may also be used in most languages.) Passed by reference always.
major – - An x-y-z triplet for the coordinates of the intersection of the ellipse and its major axis. Passed by reference always.
minor – - An x-y-z triplet for the coordinates of the intersection of the ellipse and its minor axis. Passed by reference always.
start – - The normalized parametric angle along the ellipse’s perimeter, in the direction from the major to minor axis, where the arc starts.
end – - The normalized parametric angle along the perimeter, in the direction from the major to minor axis, where the arc ends.

void HC_Edit_Grid(Key key, char const *type, Point const *origin, Point const *ref1, Point const *ref2, int count1, int count2)

Edits a grid object as it sits in the database.

A grid is a flat grid of faces, edges, and markers. Type controls the layout. It may have either of the following values:

DETAILS

quadrilateral

A quadrilateral unit is formed as:

(origin, ref1, ref1 + ref2 - origin, ref2).

If count1 is positive, the number of units is laid down along the ref1 axis starting at origin. If it is negative, the number of units is laid down along the ref1 axis and an additional count1 number of units is laid down along the negative ref1 axis. The entire count1 assembly is duplicated along the ref2 axis. If count2 is negative, the repetitions go both ways from the origin.

If both count1 and count2 are zero, the quadrilateral grid is infinite in extent. The system will make the appropriate optimizations when the grid is seen in perspective.

A “pie wedge” is formed as (origin, ref1, ref2). The pie wedge is drawn radially count1 times, and circumferentially count2 times.

radial

If count1 is given as zero, the radial grid is infinite in extent. The system will make the appropriate optimizations when the grid is seen in perspective.

Grids are grouped with shells and meshes for rendering purposes. The rendition of the interior of the grid can be adjusted with changes to face Pattern. The edges can be adjusted with Edge Pattern and Weight. The vertices can be adjusted with Marker Size and Symbol. The faces, edges, and markers can all be controlled with Visibility and Selectability.

Grids cannot be given “local” attribute values ( Open_Edge() , etc., will not work.) You can obtain some of the effect of local attributes by locally turning off hidden surfaces ( Set_Heuristics() ) and using Bring_To_Front() to lay a coarser grid with different attributes directly on top of a finer grid.

NOTES

When not using 3D “hidden surface” mode, the routine Bring_To_Front() can be helpful in forcing geometries to be drawn reliably on top of a grid.

See also

HC_Bring_To_Front, HC_Insert_Marker, HC_Insert_Polyline, HC_Insert_Polygon, HC_Insert_Shell, HC_Insert_Mesh, HC_Set_Visibility, HC_Set_Edge_Pattern, HC_Set_Edge_Weight, HC_Set_Face_Pattern, HC_Set_Marker_Symbol, HC_Set_Color.

Parameters

key – - Key to a grid object.
type – - Special constant (see details).
origin – - An x-y-z triplet for the coordinates of the “start point” of the grid. (A simple array of three elements may also be used in most languages.) Passed by reference always.
ref1 – - An x-y-z triplet for the coordinates of the first point “to the right of” origin. See details. Passed by reference always.
ref2 – - An x-y-z triplet for the coordinates of the first point “above” origin. See details. Passed by reference always.
count1 – - The number of grid units along the ref1 dimension.
count2 – - The number of grid units along the ref2 dimension.

void HC_Edit_Line(Key key, double xa, double ya, double za, double xb, double yb, double zb)

Edits a line object as it sits in the database, without deleting and reinserting.

This is a primitive way to insert lines into your scene. More flexible routines include Insert_Polyline(), which requires passing all the x-y-z values at once, and Insert_Ink(), which requires multiple calls to draw a line.

DETAILS

If you only work in two dimensions, specify za and zb as zero.

NOTES

See also

HC_Insert_Line, HC_Insert_Ink, HC_Insert_Polyline, HC_Set_Line_Pattern, HC_Set_Line_Weight, HC_Set_Color, HC_Set_Visibility, HC_Renumber_Key.

Parameters

key – - key to a line object.
xa – - x-coordinate for one end of the line segment.
ya – - y-coordinate for one end of the line segment.
za – - z-coordinate for one end of the line segment.
xb – - x-coordinate for other end of the line segment.
yb – - y-coordinate for other end of the line segment.
zb – - z-coordinate for other end of the line segment.

void HC_Edit_Infinite_Line(Key key, double xa, double ya, double za, double xb, double yb, double zb)

Modifies an existing infinite line.

See also

HC_Insert_Infinite_Line, HC_Show_Infinite_Line.

Parameters

key – - Key to the infinite line that is to be modified.
xa – - new x-coordinate for one end of the line segment.
ya – - new y-coordinate for one end of the line segment.
za – - new z-coordinate for one end of the line segment.
xb – - new x-coordinate for other end of the line segment.
yb – - new y-coordinate for other end of the line segment.
zb – - new z-coordinate for other end of the line segment.

void HC_Edit_Infinite_Ray(Key key, double xa, double ya, double za, double xb, double yb, double zb)

Modifies an existing infinite ray.

See also

HC_Insert_Infinite_Ray, HC_Show_Infinite_Ray.

Parameters

key – - Key to the infinite ray that is to be modified.
xa – - new x-coordinate for one end of the line segment.
ya – - new y-coordinate for one end of the line segment.
za – - new z-coordinate for one end of the line segment.
xb – - new x-coordinate for other end of the line segment.
yb – - new y-coordinate for other end of the line segment.
zb – - new z-coordinate for other end of the line segment.

void HC_DEdit_Infinite_Line(Key key, double xa, double ya, double za, double xb, double yb, double zb)

Similar to Edit_Infinite_Line(), but operates on double-precision data.

Parameters

key – - Key to the infinite line that is to be modified.
xa – - new x-coordinate for one end of the line segment.
ya – - new y-coordinate for one end of the line segment.
za – - new z-coordinate for one end of the line segment.
xb – - new x-coordinate for other end of the line segment.
yb – - new y-coordinate for other end of the line segment.
zb – - new z-coordinate for other end of the line segment.

void HC_DEdit_Infinite_Ray(Key key, double xa, double ya, double za, double xb, double yb, double zb)

void HC_Edit_Marker(Key key, double x, double y, double z)

Edits a marker object as it sits in the database.

The marker actually used depends on the current Marker Symbol attribute setting. The size of the marker is determined by the current Marker Size, and the Color by the “marker” color setting. Markers are not scaled with geometry.

DETAILS

There is no “polymarker” routine in HOOPS. A mesh with edges and faces turned off (in the segment, not locally one-by-one!) is a reasonably compact and fast alternative.

NOTES

The marker generated always faces to the front on the final screen display.

Due to the floating point to integer round-off error, the positioning of markers, particularly the asterisk, can sometimes be off by one pixel.

RESTRICTIONS

See also

HC_Insert_Marker, HC_Insert_Line, HC_Insert_Polygon, HC_Insert_Circle, HC_Insert_Mesh, HC_Set_Marker_Symbol, HC_Set_Marker_Size, HC_Set_Color, HC_Set_Visibility, HC_Renumber_Key.

Parameters

key – - Key to a marker object.
x – - x-coordinate of the marker in object space.
y – - y-coordinate of the marker in object space.
z – - z-coordinate of the marker in object space.

void HC_Edit_Cylinder(Key key, Point const *p1, Point const *p2, double radius, char const *cap)

Edits a cylinder object as it sits in the database without deleting and reinserting.

Cylinders are specified with two points and a radius, plus an options string to specify which, if any, of the end caps are to be drawn. The options string has only four legal values: “none”, “first”, “second” and “both”.

DETAILS

Cylinders were introduced as a primitive primarily to allow for a higher-performance way to represent piping systems than what was previously available via shells. The benefits come in the form of both improved rendering speed and lower memory footprint.

Standard edge and face visibilities affect cylinders. When edges are visible, the edges are simply two circles at the ends connected by lengthwise struts. The edges around the end-caps are considered hard edges, and the lengthwise struts can be silhouette edges under the right viewing angles. When markers are visible, there will be one marker placed in the center of each end cap.

Like shells, cylinders have LOD representations. Unlike shells, however, the only form of LOD allowed on cylinders is simple changes in the tessellation resolution (i.e. it is not possible to use HC_Open_LOD to insert arbitrary geometry or modify the contents of a LOD). The tessellation resolutions of cylinders is given as an array of integers, one for every LOD level (see Set_Rendering_Options() ). If the tessellation level is set to 0, the cylinder will be drawn as a line along its axis. If set to -1, it will be suppressed completely.

See also

HC_Insert_Cylinder, HC_Show_Cylinder

Parameters

key – - Key to a cylinder object.
p1 – - Center of the first end of the cylinder.
p2 – - Center of the second end of the cylinder.
radius – - Radius of the cylinder.
cap –
- String specifying which ends to cap, either

”first”, “second”, “none”, or “both”

void HC_Edit_PolyCylinder_Points(Key key, int offset, int delete_count, int insert_count, Point const points[])

Edits an existing polycylinder by inserting or deleting its points.

Parameters

key – - key to a polycylinder object
offset – - offset into the polycylinder’s points list to begin editing
delete_count – - number of points to delete
insert_count – - number of points to insert
points – - the points to insert into this polycylinder, or null if deleting

void HC_Edit_PolyCylinder_Radii(Key key, int offset, int delete_count, int insert_count, float const radii[])

Edits an existing polycylinder by inserting or deleting its points.

Parameters

key – - key to a polycylinder object
offset – - offset into the polycylinder’s radii list to begin editing
delete_count – - number of radii to delete
insert_count – - number of radii to insert
radii – - the radii to insert into this polycylinder, or null if deleting

void HC_DEdit_PolyCylinder_Points(Key key, int offset, int delete_count, int insert_count, DPoint const points[])

Similar to Edit_PolyCylinder_Points, but operates on double-precision data.

Parameters

key – - key to a polycylinder object
offset – - offset into the polycylinder’s points list to begin editing
delete_count – - number of points to delete
insert_count – - number of points to insert
points – - the points to insert into this polycylinder, or null if deleting

void HC_DEdit_PolyCylinder_Radii(Key key, int offset, int delete_count, int insert_count, double const radii[])

Similar to Edit_PolyCylinder_Radii, but operates on double-precision data.

Parameters

key – - key to a polycylinder object
offset – - offset into the polycylinder’s radii list to begin editing
delete_count – - number of radii to delete
insert_count – - number of radii to insert
radii – - the radii to insert into this polycylinder, or null if deleting

void HC_Edit_PolyCylinder(Key key, int p_count, Point const pts[], int r_count, float const radii[], char const *capping)

Edits a polycylinder as it sits in the database, without deleting and reinserting.

A polycylinder is a multi-segmented cylinder that can have varying radii at the ends of each segment.

DETAILS

This primitive can be used to create cones.

NOTES

Any local vertex attributes will be thrown away if the polycylinder is edited.

RESTRICTIONS

See also

HC_Insert_PolyCylinder, HC_Insert_Polyline

Parameters

key – - key to a polycylinder object.
p_count – - number of items in pts
pts – - Vector of x-y-z triplets for the coordinates of the center of the polycylinder. (A simple N x 3 array may also be used.) Passed by reference always.
r_count – - number of items in radii
radii – - array of radius lengths as measured from the centerline
capping – - string specifying which ends to cap, either “first”, “second”, “none”, or “both”

void HC_Edit_PolyCylinder_With_Basis(Key key, int p_count, Point const pts[], int r_count, float const radii[], char const *capping, Vector const basis[])

Edits the polycylinder’s points, radii, and vector basis.

Parameters

key – - key to a polycylinder object
p_count – - number of points in pts
pts – - the new points
r_count – - number of radii in radii
radii – - the new radii
capping – - string specifying which ends to cap, either “first”, “second”, “none”, or “both”
basis – - the new basis

Key HC_Copy_Geometry(Key key, char const *segment)

Copies the geometry referred to by key to the given segment.

See also

HC_Copy_Segment

Parameters

key – HOOPS key the the geometry in question.
segment – Name of the segment to which the geometry should be moved.

Returns

The key to the duplicate geometry.

Key HC_Copy_Segment(char const *old_seg_name, char const *new_seg_name)

Completely duplicates a segment.

Copy_Segment() duplicates the contents of old_seg_name and inserts them into new_seg_name. “Contents” consists of all the attributes, styles, includes, geometry, and subsegments, and all the attributes, styles, includes and geometry in all the subsegments. When Copy_Segment() finishes, the segment tree starting at new_seg_name will be an exact copy of old_seg_name. It is not necessary to use a “…” to get the whole tree copied, because this is HOOPS normal mode.

DETAILS

If you just want the same piece of a picture to appear in two different contexts, you can redraw that piece in the “?Include

Library…” segment tree. Then request an Include_Segment() in each place where the piece is needed. Doing it this way helps the system compute displays efficiently and helps you stay organized. (If you find yourself making a copy just because you need to override an attribute setting of the original, consider making a utility segment that has the original’s contents, minus the offending attribute(s), and have other parts of the application refer to that utility segment.)

If the new_seg_name specification contains a wildcard on the end, that wildcard gets matched with the lowest-level name on the incoming segment. For example, a copy from “A/B/C” to “D/*” creates a segment named “D/C”. More commonly, you would use a wildcard on the new_seg_name segment name only if you were using wildcards on the input name too, such as copying from “A/B/*” to “D/*”.

If new_seg_name does not exist, it is created. If new_seg_name existed but was not empty, Copy_Segment() will complain.

NOTES

If new_seg_name is a blank or null string, a new “nameless” segment (see Open_Segment() ) is created.

If more than one output segment is created, and you used KCopy_Segment() , you will get an error when the system tries to return the key.

See also

HC_Include_Segment, HC_Rename_Segment, HC_Open_Segment, HC_Close_Segment, HC_Delete_Segment.

Parameters

old_seg_name – - Segment(s) to be Copied. Can contain wildcards.
new_seg_name – - New name to use. Can contain a “/*” on the end, but cannot contain any other wildcards (see details).

Returns

The key to the new duplicate segment.

Key HC_Create_Segment(char const *segment)

Brings a segment into existence without opening it.

Open_Segment() is the normal method for bringing segments into existence - it both creates the segment (if it does not already exist) and readies it to receive geometry, subsegments, etc.

DETAILS

Once in a while, you need to create a segment in advance of being ready to insert information into it. Include_Segment() and Style_Segment() , for example, require that the specified segment exist at the time of the call. Create_Segment() is an easy way to make the segment exist even if you’re not ready to put something into it.

Create_Segment() is provided as a utility routine. It is absolutely identical to an Open_Segment() followed immediately by a Close_Segment() . You can open the segment again later, by name of course. Or if it’s more convenient, by the key returned from Create_Segment() .

See also

HC_Open_Segment, HC_Open_Segment_By_Key, HC_Close_Segment, HC_Include_Segment, HC_Style_Segment, HC_Open_Geometry.

Parameters: segment – - Name of the segment.
Returns: The key to the created segment.

Key HC_Include_Segment(char const *include)

Leaves a note for the system directing it to grab a copy of another segment whenever the current one is displayed.

Include_Segment() inserts a request into the currently open segment. The request asks that whenever this segment is displayed, the referenced segment should be searched for and included as part of this scene - as if it had been built right into the segment as a subsegment. The included segment comes complete with all its attributes and subsegments, and its own styles and inclusions. It is detached from its regular context. However, if the segment that owns the segment being included has an opinion about something, it doesn’t matter.

DETAILS

The primary use of “including” - as opposed to chopping up a segment into subsegments to improve organization - is when the same scene or object needs to appear in several or many contexts. The include can be as simple as an icon or as complex as a complete scene, of which you’re going to present multiple simultaneous views on the screen.

The difference between Include_Segment() and Copy_Segment() is that Copy_Segment() actually makes a copy of the referenced segment. You would perform a Copy if you need to make changes and want to leave the original segment alone. If you simply want to ‘reuse’ a segment by referencing it, you would Include. Think of an Include as a Unix directory soft link.

Includes follow the same inheritance rules as sub-segments. First, if the include has an opinion about an attribute setting, its opinion is used (otherwise the including segment’s is used). Second, the include cannot affect the display of the including segment or anything higher up in the tree.

By convention, includes live in the “Include Library” segment tree - their full names should begin with “?Include Library/”. This aids in making sure they don’t pop up on their own as they would if they were in “?Picture/…”. If you do want them in the “Picture” tree, you’ll have to protect them from being displayed on their own. The easiest way to do this is to invent your own “include library” segment (down in the picture tree), and to set Visibility to “Off” on the library segment itself.

The segment being included must exist at the time Include_Segment() is called, so the system can make the connection.

NOTES

To be consistent with all the other routines that “Insert” picture pieces into a segment, this routine might be better named “Insert_Include_Request”. But just plain Include_Segment() is nicely short.

The “as-included-by” segment name syntax is ignored when passed to HOOPS as a segment name. This makes it hard to accurately requeue an arbitrary Selection Event.

RESTRICTIONS

See also

HC_Copy_Segment, HC_Flush_Contents, HC_Style_Segment, HC_Open_Segment, HC_Set_Visibility, HC_Conditional_Include

Parameters: include – - Name, possibly including wildcards and lists, of extra segment(s) to be included when displaying the current segment.
Returns: The new key for the segment as included, as opposed to its original key

Key HC_Include_Segment_By_Key(Key seg_key)

Similar to Include_Segment(), but operates on an object referenced by an HC_KEY.

See also

HC_Include_Segment()

Parameters: seg_key – - Unique numeric identifier to the segment to be included. Accepted as argument in Open_Segment_By_Key().
Returns: The new key for the segment as included, as opposed to its original key

Key HC_Insert_Area_Light(int count, Point const points[], char const *listptr)

Inserts an area light.

Radiosity is an intensive, iterative calculation based on how light bounces around an environment – a light bulb (point light) near the ceiling lights up the ceiling brightly close to it, and less further away, and less down the walls and the floor. Some of the wall and floor areas are directly shadowed by furniture, but light bouncing off the first lit areas can add a little to those other areas, and a little more to the areas that were first lit. These newly lit/brightened areas now light up more, and so on until a limit is reached – either a number of iterations or the lighting levels have stabilized within a tolerance.

DETAILS

To this end, an area light is an emissive polygon – a polygon that is considered a single extended light source, such as the rectangular diffuser found on many fluorescent fixtures. Area lights do have an effect on the scene lighting - they are treated by the code as if they were one or two very wide spotlights with a falloff.

Parameters

count – – number of points
points – – float triples defining the area (count & points exactly as in Insert_Polygon)
options – – “front|back|both”, which determines which side(s) of the polygon emit light

Returns

The key to the inserted light, or -1 if an error occurred.

Key HC_Insert_Circle(Point const *point1, Point const *point2, Point const *point3)

Generates a flat, infinitely thin, filled circle.

A closed, flat, filled-in circle is added to the current segment.

DETAILS

Circles are grouped with ellipses, polygons, shells, and meshes for rendering purposes. The rendition of the interior of the circle can be adjusted with changes to face color and face pattern. The circumference of a circle can be made distinct from the interior through the use of edge color, edge pattern and edge weight. A circle’s visibility and selectability are controlled by the “edge”, “face”, and “polygon” keywords.

Make sure the points are not colinear. The system checks and issues an error message if all three points lie on a line, or if two points are coincident.

NOTES: If you only work in two dimensions, specify all the z coordinates as zero. The system will automatically take note.

If you want to create a wire circle, we recommend using an elliptical arc (with start=0.0 and end=1.0) instead of inserting a circle and then turning off the visibility of faces. The following code snippet is an example of how to create a unit wire circle centered at the origin in the xy plane using Insert_Elliptical_Arc():

Point center, major, minor;

center.x=0; center.y=0; center.z=0;
major.x=1; major.y=0; major.z=0;
minor.x=0; minor.y=1; minor.z=0;

HC_Open_Segment( "circle" );
HC_Insert_Elliptical_Arc(&center, &major, &minor, 0, 1);
HC_Close_Segment();

See also

HC_Insert_Circle_By_Radius, HC_Insert_Ellipse, HC_Insert_Circular_Arc, HC_Insert_Circular_Chord, HC_Insert_Circular_Wedge, HC_Insert_Elliptical_Arc.

Parameters

point1 – - An x-y-z triplet for the coordinates of one of three on the circumference of the circle. A simple array of three elements may also be used for each parameter. Passed by reference always.
point2 – - As above.
point3 – - As above.

Returns

The key to the inserted geometry, or -1 if an error occurred.

Key HC_Insert_Circular_Arc(Point const *point1, Point const *point2, Point const *point3)

Generates a portion of the circumference of a circle.

A portion of the circumference of a circle is added to the current segment. The order of the specified points is important. Specifically, the arc begins at the first point, is drawn through the second point and continues through the third point.

DETAILS

Circular arcs are grouped with lines, polylines, and elliptical arcs for rendering purposes. The rendition of an arc can be altered through the use of line color, line weight, and line pattern. An arc’s visibility and selectability can be controlled by the “line” or “polyline” keywords.

If you only work in two dimensions, specify all the z coordinates as zero.

NOTES

Make sure the points are not colinear. The system issues an error message if all three points lie on a line, or if two points are coincident.

Zooming in close on very large circular arcs results in a linear appearance.

See also

HC_Insert_Circle, HC_Insert_Ellipse, HC_Insert_Elliptical_Arc, HC_Insert_Polyline.

Parameters

point1 – - An x-y-z triplet for the coordinates of one of three ordered on the circumference of the circle. A simple array of three elements may also be used for each parameter. Passed by reference always.
point2 – - As above.
point3 – - As above.

Returns

The key to the inserted geometry, or -1 if an error occurred.

Key HC_Insert_Circular_Chord(Point const *point1, Point const *point2, Point const *point3)

Generates a polygon describing a portion of a circle.

A portion of a circle is added to the current segment. The order of the specified points is important. Specifically, the chord begins at the first point, is drawn through the second point and continues through the third point. A line connects the first and third points. The chord is defined as the area bounded by the points.

DETAILS

Circular chords are grouped with ellipses, polygons, shells, and meshes for rendering purposes. The rendition of the interior of the chord can be adjusted with changes to face color and face pattern. The circumference of a chord can be made distinct from the interior through the use of edge color, edge pattern and edge weight. A chord’s visibility and selectability are controlled by the “edge”, “face”, and “polygon” keywords.

If you only work in two dimensions, specify all the z coordinates as zero.

NOTES

You must make sure that the supplied points are not colinear. The system will issue an error message if all three points lie on a line, or if two points are coincident.

See also

HC_Insert_Circle, HC_Insert_Circular_Arc, HC_Insert_Circular_Wedge, HC_Insert_Polygon.

Parameters

point1 – - An x-y-z triplet for the coordinates of one of three ordered points on the circumference of the circle. A simple array of three elements may also be used for each parameter. Passed by reference always.
point2 – - As above.
point3 – - As above.

Returns

The key to the inserted geometry, or -1 if an error occurred.

Key HC_Insert_Circular_Wedge(Point const *point1, Point const *point2, Point const *point3)

Generates a wedge shaped polygon representing a portion of a circle.

A portion of a circle is added to the current segment. The order of the specified points is important. Specifically, the wedge begins at the first point, is drawn through the second point and continues through the third point. The center of a circle defined by the 3 points is computed. Lines are drawn from the first point to the center and from the third point to the center. The wedge is defined as the area bounded by the points.

DETAILS

Circular wedges are grouped with ellipses, polygons, shells and meshes for rendering purposes. The rendition of the interior of the wedge can be adjusted with changes to Face Color and Face Pattern. The circumference of a wedge can be made distinct from the interior through the use of Edge Color, Edge Pattern and Edge Weight. A chord’s Visibility and Selectability are controlled by the “edge”, “face”, and “polygon” keywords.

If you only work in two dimensions, specify all the z coordinates as zero.

NOTES

You must make sure that the points are not colinear. The system issues an error message if all three points lie on a line, or if two points are coincident.

Because of the way the center of a wedge is computed, it may be expedient to explicitly set the circular center via Set_Circular_Center(). This will help prevent rounding errors, especially in cases where the arc is very small.

See also

HC_Insert_Circle, HC_Insert_Circular_Arc, HC_Insert_Circular_Chord, HC_Insert_Polygon, HC_Set_Circular_Center.

RESTRICTIONS

Parameters

point1 – - An x-y-z triplet for the coordinates of one of three ordered points on the rounded portion of the wedge. A simple array of three elements may also be used for each parameter. Passed by reference always.
point2 – - As above.
point3 – - As above.

Returns

The key to the inserted geometry, or -1 if an error occurred.

Key HC_Insert_Cutting_Plane(double a, double b, double c, double d)

Creates a special geometric object that “cuts away” part of the normal scene.

3D objects can be hard to comprehend when depicted on a 2D computer screen. One of the techniques to aid understanding is to slice the object open. When inserted with other geometry in a HOOPS Visualize scene, a cutting plane will cause all geometry on the “open” side of the plane to vanish.

DETAILS

A HOOPS Visualize “scene” is the segment tree and all the geometry within a single HOOPS Visualize window. Cutting planes can be anywhere in the segment tree - they will still apply to the whole scene (with the exceptions noted below.) This allows the cutting plane to have its own attribute context - most importantly, segment name and current modelling matrix. It is the same rule followed by light sources.

Planes have two sides. If you consider the (a,b,c) part of the plane equation as a vector pointing out of the plane, that vector is normal to the plane and is, by convention, pointing out into the open cut-away territory. The side of the plane “behind” the normal vector is, by convention, the part of the scene retained by the cutting action.

There is no predefined limit to the number of cutting planes that can be in a scene. However, there might be some limit as to how many planes can be handled by the hardware before the system has to switch to software mode. See the “hardware cutting

planes” in Show_Device_Info() for details. Cutting planes have no effect on each other - geometry is removed if it is cut away by

any plane.

There is a small performance penalty when using cutting planes.

NOTES

Cutting planes do not act within a marker symbol, a wide line, or a single text character (unless the text is fully-transformable.)

There are a few exceptions to the cutting action. First, lights are completely exempted - they are never cut away. Second, if “cutting plane” visibility is “off” for the branch of the segment tree in which the cutting plane is located, the cutting plane is turned off completely. Finally, if “cutting plane” visibility is “off” for a branch of the tree in which regular geometry is located, that geometry will not “receive” cutting planes: it will be exempted from being cut. This permits a partial cut-away to be drawn.

The “local cutting planes” rendering option (see Set_Rendering_Options()), if active where the cutting plane was inserted, will cause the cutting plane to only affect geometry below its owning segment. By default, cutting planes are not local.

Although this function accepts double values, they are truncated to float internally. To explicitly use double values, use DInsert_Cutting_Plane.

On some devices setting the “no clipping” heuristic may have the side effect of disabling cutting planes.

RESTRICTIONS

Cutting planes cannot be scaled by 0, and will show numerical problems if scaled by very small values.

See also

HC_DInsert_Cutting_Plane, HC_Show_Device_Info, HC_Set_Visibility, HC_Set_Heuristics.

Parameters

a – - The parameters of an equation of the form ax + by + cz + d = 0, defining a plane.
b – - As above.
c – - As above.
d – - As above.

Returns

The key to the inserted geometry, or -1 if an error occurred.

Key HC_Insert_Cylinder(Point const *center_point_1, Point const *center_point_2, double radius, char const *cap)

Inserts a cylinder into the currently open segment.

Cylinders are specified with two points and a radius, plus an options string to specify which, if any, of the end caps are to be drawn. The options string has only four legal values: “none”, “first”, “second” and “both”.

DETAILS

Cylinders were introduced as a primitive primarily to allow for a higher-performance way to represent piping systems than what was previously available via shells. The benefits come in the form of both improved rendering speed and lower memory footprint.

Standard edge and face visibilities affect cylinders. When edges are visible, the edges are simply two circles at the ends connected by lengthwise struts. The edges around the end-caps are considered hard edges, and the lengthwise struts can be silhouette edges under the right viewing angles. When markers are visible, there will be one marker placed in the center of each end cap.

Like shells, cylinders have LOD representations. Unlike shells, however, the only form of LOD allowed on cylinders is simple changes in the tessellation resolution (i.e. it is not possible to use HC_Open_LOD to insert arbitrary geometry or modify the contents of a LOD). The tessellation resolutions of cylinders is given as an array of integers, one for every LOD level (see Set_Rendering_Options()). If the tessellation level is set to 0, the cylinder will be drawn as a line along its axis. If set to -1, it will be suppressed completely.

If the radius is 0, the cylinder will be rendered as a line.

Arbitrary LOD geometry is not allowed. If such functionality is required, shells, not cylinders, are the appropriate primitive.

RESTRICTIONS

Cylinders are never broken lengthwise into pieces, making it impossible to have a specular highlight in the middle of a cylinder using Gouraud shading (though it would be possible with Phong).

Unlike shells, the individual faces, edges, and vertices of cylinders may not be assigned local attributes. Therefore, it is not possible to apply textures.

There is currently no mechanism to assign a starting point for the faceting so that the cylinder will exactly match up with other geometry, though cylinders should match up with each other.

There is currently no “draw 3d cylinder” I.M. callback point.

See also

HC_Show_Cylinder

Parameters

center_point_1 – - Center of the first end of the cylinder.
center_point_2 – - Center of the second end of the cylinder.
radius – - Radius of the cylinder.
cap – - String specifying which ends to cap, either “first”, “second”, “none”, or “both”

Returns

The key to the inserted geometry, or -1 if an error occurred.

Key HC_Insert_Sphere(Point const *center, double radius, Vector const *axis, Vector const *ortho)

Generates a sphere.

The sphere primitive is tesselated at draw time which can greatly reduce the memory footprint of an application in which spheres are widely used. The tesselation of the sphere is controlled by the “sphere” option within the “tesselation” rendering option.

DETAILS

See also

HC_Insert_Circle, HC_Insert_Ellipse, HC_Insert_Circular_Arc, HC_Insert_Circular_Chord, HC_Insert_Circular_Wedge, HC_Insert_Elliptical_Arc, HC_Insert_Polygon, HC_Set_Visibility, HC_Set_Edge_Pattern, HC_Set_Edge_Weight, HC_Set_Face_Pattern, HC_Set_Color, HC_Renumber_Key.

Parameters

center – - An x-y-z triplet for the coordinates of center the sphere. (A simple array of three elements may also be used in most languages.) Passed by reference always.
radius – - Length of the radius of the sphere.
axis – - Vector that points in the longtitudal/vertical direction. If null then a default value of <0,10,0> is applied.
ortho – - Vector that points in the latitudal/horizontal direction. If null then a default value of <1,0,0> is applied.

Returns

The key to the inserted geometry, or -1 if an error occurred.

Key HC_Insert_Circle_By_Radius(Point const *center, double radius, Vector const *normal)

Generates a flat, infinitely thin, colored-in circular object.

A closed, flat, colored-in circle is added to the current segment.

DETAILS

Circles are grouped with ellipses, polygons, shells and meshes for rendering purposes. The rendition of the interior of the circle can be adjusted with changes to Face Color and Face Pattern. The circumference of a circle can be made distinct from the interior through the use of Edge Color, Edge Pattern and Edge Weight. A circle’s Visibility and Selectability are controlled by the “edge”, “face”, and “polygon” keywords.

If normal is null, it is assumed to be a 2D circle with normal==<0,0,1>

Circles would have no memory of how they were inserted, so if they are saved and restored, they convert to the default of looking as if they had been inserted by HC_Insert_Circle. Additionally, there will be no difference in what is reported by Begin_Contents_Search/Find_Contents, and no hsf changes.

NOTES
RESTRICTIONS

See also

HC_Insert_Circle, HC_Insert_Ellipse, HC_Insert_Circular_Arc, HC_Insert_Circular_Chord, HC_Insert_Circular_Wedge, HC_Insert_Elliptical_Arc, HC_Insert_Polygon, HC_Set_Visibility, HC_Set_Edge_Pattern, HC_Set_Edge_Weight, HC_Set_Face_Pattern, HC_Set_Color, HC_Renumber_Key.

Parameters

center – - An x-y-z triplet for the coordinates of center the circle. (A simple array of three elements may also be used in most languages.) Passed by reference always.
radius – - Length of the radius of the circle.
normal – - Vector that is perpendicular to the plane of the circle

Returns

The key to the inserted geometry, or -1 if an error occurred.

Key HC_Insert_Distant_Light(double di, double dj, double dk)

Inserts a distant point source of light into your scene.

Normally, when you set the color of a surface (a polygon, mesh, or shell face) HOOPS Visualize draws the surface in the specified color. Visualize will optimize scenes that contain no lights by skipping lighting calculations. If a scene has one or more lights in it, lighting calculations are made. The lighting calculations compute the color of each face using the color and orientation of the lights.

DETAILS

In HOOPS Visualize, there are four possible sources of light:

A scene’s ambient light intensity as defined by Set_Color()
Individual distant (point) lights created by Insert_Distant_Light()
Individual local (point) lights created by Insert_Local_Light()
Individual directional local (point) lights created by Insert_Spot_Light()

A distant light is similar to the sun: it’s so far away that all the light rays arriving from it are parallel. The only important considerations are the light’s color and direction - not its position. The direction specified by Insert_Distant_Light() can later be modified by the modelling transformations. The color is defined by the “lights” option of Set_Color() . Unlike local, spot, and area lights, distant lights illuminate all surfaces in a scene with equal intensity (the intensity defined by Set_Color() ).

The scope of a light is always its containing window. Even if the light is many levels down from the window in the segment tree, it still “shines light” on everything in the scene (except as noted below, under “light visibility”). In fact, if you want to have several lights of different colors, you must put them in different segments in order to set the different color attributes. You could also put a light in its own subsegment so as to make it orbit your scene using Rotate_Object().

If the light is shining on one side of a given face and you’re looking at the other side, the side you’re looking at is in the shadow of the face and is not lit by the light. Beyond this effect, shadows are not computed by the standard shaders (“no

lighting interpolation”, Gouraud, and Phong). If you request shadows in your scene via advanced radiosity or ray-trace computations (see Set_Rendering_Options() ), shadows generated from a specific light can be turned off with Set_Visibility(“shadows = no emitting”).

NOTES

The number of lights you can have in a scene is almost unlimited. Since the screen isn’t able to keep getting brighter and brighter as additional lights are inserted, HOOPS Visualize scales the total brightness by the total brightness of all the light sources. Please see the “light scaling” Driver Option for a means of overriding this calculation.

The “fixed colors” driver option might also be of interest when using lights.

In the current implementation, lights only affect faces. Lines and edges are still drawn in the standard way, with static colors.

Turning off the visibility of a light makes that light cease to exist for the purpose of performing, a lighting calculation. This may be a convenient way to enter and leave “lighted” mode in your program.

Turning off the light visibility also prevents a light placed elsewhere in the segment tree (but within the same window) from shining through the local geometry. This could be useful for inserting geometries that don’t need to be lit, such as annotations, into a lighted window.

Of the five types of possible light sources listed above, an ambient light is not sufficient to trigger lighting calculations. To force the system to perform lighting calculations, insert a black distant light.

See also

HC_Insert_Local_Light, HC_Insert_Spot_Light, HC_Renumber_Key, HC_Rotate_Object, HC_Rotate_Object_Offaxis, HC_Set_Color, HC_Set_Driver_Options, HC_Set_Rendering_Options, HC_Set_Visibility, HC_Show_Distant_Light, HC_Move_Distant_Light.

RESTRICTIONS: For DX11, the maximum number of lights is 15.

Parameters

di – - Vector describing the direction in which the light lies, infinitely far away.
dj – - As above.
dk – - As above.

Returns

The key to the inserted geometry, or -1 if an error occurred.

Key HC_Insert_Ellipse(Point const *center, Point const *major, Point const *minor)

Generates a flat, infinitely thin, colored-in elliptical object.

A closed, flat, colored-in ellipse is added to the current segment.

DETAILS

Ellipses are grouped with circles, polygons, shells, and meshes for rendering purposes. The rendition of the interior of the ellipse can be adjusted with changes to face color and face pattern. The circumference of an ellipse can be made distinct from the interior through the use of edge color, edge pattern and edge weight. An ellipse’s visibility and selectability are controlled by the “edge”, “face”, and “polygon” keywords.

If you only work in two dimensions, specify all the z coordinates as zero.

NOTES

Make sure the points are not colinear. The system checks and issues an error message if all three points lie on a line, or if two are coincident.

See also

HC_Insert_Circle, HC_Insert_Circular_Arc, HC_Insert_Elliptical_Arc, HC_Insert_Polygon, .

Parameters

center – - An x-y-z triplet for the coordinates of the center of the ellipse. (A simple array of three elements may also be used in most languages.) Passed by reference always.
major – - An x-y-z triplet for the coordinates of the intersection of the ellipse and its major axis. Passed by reference always.
minor – - An x-y-z triplet for the coordinates of the intersection of the ellipse and its minor axis. Passed by reference always.

Returns

The key to the inserted geometry, or -1 if an error occurred.

Key HC_Insert_Elliptical_Arc(Point const *center, Point const *major, Point const *minor, double start, double end)

Generates a portion of the perimeter of an ellipse.

A portion of the perimeter of an ellipse is added to the current segment.

DETAILS

The direction of the perimeter is determined by the shortest path between the points used to define the major and minor axes. The starting and ending points are the parametric angular distances, specified between 0.0 and 1.0, along the perimeter. For example, a quarter of an ellipse could be specified with start and end points of 0.25 and 0.5, respectively.

Elliptical arcs are grouped with lines, polylines, and circular arcs for rendering purposes. The rendition of an arc can be altered through the use of line color, line weight and line pattern. An ellipse’s visibility and selectability can be controlled by the “line” or “polyline” keywords.

If you only work in two dimensions, specify all the z coordinates as zero. The system will automatically take note.

NOTES

Make sure the points are not colinear. The system checks and issues an error message if all three points lie on a line, or if two points are coincident.

Zooming in close on very large elliptical arcs results in a flat appearance.

See also

HC_Insert_Ellipse, HC_Insert_Circle, HC_Insert_Circular_Arc, HC_Insert_Polyline.

Parameters

center – - An x-y-z triplet for the coordinates of the center of an ellipse. (A simple array of three elements may also be used in most languages.) Passed by reference always.
major – - An x-y-z triplet for the coordinates of the intersection of the ellipse and its major axis. Passed by reference always.
minor – - An x-y-z triplet for the coordinates of the intersection of the ellipse and its minor axis. Passed by reference always.
start – - The normalized parametric angle along the ellipse’s perimeter, in the direction from the major to minor axis, where the arc starts.
end – - The normalized parametric angle along the perimeter, in the direction from the major to minor axis, where the arc ends.

Returns

The key to the inserted geometry, or -1 if an error occurred.

Key HC_Insert_Grid(char const *type, Point const *origin, Point const *ref1, Point const *ref2, int count1, int count2)

Generates a flat array of edges, faces, and/or markers.

A flat grid of faces, edges, and markers is added to the current segment. Type controls the layout. It may have either of the following values:

DETAILS

quadrilateral

A quadrilateral unit is formed as (origin, ref1, ref1 + ref2 - origin, ref2). If count1 is positive, the number of units is laid down along the ref1 axis starting at origin. If it is negative, the number of units is laid down along the ref1 axis and an additional count1 number of units is laid down along the negative ref1 axis. The entire count1 assembly is duplicated along the ref2 axis. If count2 is negative, the repetitions go both ways from the origin.

If both count1 and count2 are zero, the quadrilateral grid is infinite in extent. The system will make the appropriate optimizations when the grid is seen in perspective.

radial

A “pie wedge” is formed as (origin, ref1, ref2). The pie wedge is drawn radially count1 times, and circumferentially count2 times.

If count1 is given as zero, the radial grid is infinite in extent. The system will make the appropriate optimizations when the grid is seen in perspective.

Grids are grouped with shells and meshes for rendering purposes. The rendition of the interior of the grid can be adjusted with changes to face pattern. The edges can be adjusted with edge pattern and weight. The vertices can be adjusted with marker size and symbol. The faces, edges, and markers can all be controlled with visibility and selectability.

In this release, grids can not be given “local” attribute values ( Open_Edge() , etc., will not work.) You can obtain some of the effect of local attributes by locally turning off hidden surfaces ( Set_Heuristics() ) and using Bring_To_Front() to lay a coarser grid with different attributes directly on top of a finer grid.

NOTES

If you are not in 3-D “hidden surface” mode, the routine Bring_To_Front() can be helpful in forcing geometries to be drawn reliably on top of a grid.

See also

HC_Bring_To_Front, HC_Insert_Marker, HC_Insert_Polyline, HC_Insert_Polygon, HC_Insert_Shell, HC_Insert_Mesh, HC_Set_Edge_Pattern, HC_Set_Edge_Weight, HC_Set_Marker_Symbol.

Parameters

type – - Special constant (see details).
origin – - An x-y-z triplet for the coordinates of the “start point” of the grid. (A simple array of three elements may also be used in most languages.) Passed by reference always.
ref1 – - An x-y-z triplet for the coordinates of the first point “to the right of” origin. See details. Passed by reference always.
ref2 – - An x-y-z triplet for the coordinates of the first point “above” origin. See details. Passed by reference always.
count1 – - The number of grid units along the ref1 dimension.
count2 – - The number of grid units along the ref2 dimension.

Returns

The key to the inserted geometry, or -1 if an error occurred.

Key HC_Insert_Image(double x, double y, double z, char const *format, int width, int height, void const *data)

Inserts a pixel-based image in the HOOPS Visualize database.

Images are intended for the display of raster arrays of pixels. They are unique in that they are laid out in terms of screen space - once the center has been located (transformed from object space) everything else is defined solely in terms of the pixels on the screen of your current display device. Images are extremely display-dependent. Images look different on different devices depending on their resolutions, aspect ratios, and, indeed, whether or not they actually display in terms of pixels.

Supported Options:: discard, down-sample, grayscale, local, name, mapped 16, mapped 8, mapped, RGB, RGBA, size, compression quality, texture options,
DETAILS

The _By_Ref() (“by reference”) routines differ from the regular routines. The system is allowed not to make a copy of your data (at the system’s option) but instead will remember where your image was located. Then, whenever the pixels need to be redisplayed, the image originally passed in data is used, not an internal copy. This can speed up the call to Insert_Image() and it can save memory. But be careful - when you insert “by reference”, you are guaranteeing that data is going to remain valid and you’re not going to touch it (except via Edit_Image() ) until such time as the whole Image database entry gets deleted. Also, as mentioned, the system can make a copy anyhow if it needs to. So don’t assume Edits will be readable in the original array.

The following choices for “format” are recognized:

discard If set, then the image data will be purged from the HOOPS data once the texture is loaded into video memory. This will result in the memory associated with that image being returned to the system. Note, the image database item will remain in the HOOPS database and can be returned to the user via a call to Show_Image().

[no] down-sample If this is set, images will have a bilinear filter applied to them. This typically makes images look smoother, especially if zoomed in. However, if there are hard edges (e.g. a checker board) it can make the image look unnecessarily blurry. Default = “down-sample”

grayscale Treats data as a two-dimensional array of single byte entries where each byte defines the luminance of the pixel.

[no] local If set, the implicit texture created will be local to the currently open segment. Default = “no local”

name = <identifier> The name which will be applied to the texture that will be implicitly defined with the options specified in ‘texture options’. Providing no texture option string will mean that a texture is then created with default texture options. If you do not want an implicitly texture created you should not provide a name to the image.

mapped 16 Treats data as a two-dimensional array of 16-bit color map indices (two consecutive bytes per pixel). The byte ordering within data is identical to casting an array of short integers. The pixel values defined here are not full-fledged HOOPS color triplets or strings; they are just look-up indices. This lets you “color by number”, while the actual colors are defined indirectly by the current “Color Map” attribute. You must define an appropriate color map to match your image. Also, the color look-up is performed at Update time, not just at declaration time - changes to the color map will be reflected in the appearance of images that already exist.

mapped 8 Identical to “mapped 16”, but treats data as a two-dimensional array of 8-bit color map indices.

mapped “Mapped” is a convenience synonym for “mapped 8”.

RGB Treats data as a two-dimensional array of pixels, where each pixel’s color is described by three bytes: one for the red, green, and blue intensities. The first three bytes in data describe the red, green, and blue components of the upper-left-most image pixel. The following three data bytes describe the next pixel to the right. The next scan line begins at (width*3) in the array. When using RGB formatted images on color-mapped devices (such as 8-bit plane displays), HOOPS will “dither” the image using fixed colors. The larger a fixed color table you choose via Set_Driver_Options() , the more accurate the dither will be. If you plan on using the virtual “image driver”, you must select the RGB format for the image into which the driver will draw. For full information on scan-converting into a HOOPS image, see the “Image Driver” section of your installation guide.

RGBA Treats data as a two-dimensional array of pixels, where each pixel’s color is described by four bytes: one for each of the red, green, and blue intensities, along with one for alpha. A non-zero alpha value indicates that the pixel is illuminated using the RGB. The layout of the data matches that of RGB with the exception that four instead of three bytes per pixel are used.

size = ((float) width units, (float) height units) size = <float> units Scale for an image where units is either “oru”, “sru” or “pixels”. “size = <float> units” will preserve aspect ratio.

compression quality = <float> Compression quality is a floating point value between 0 and 1. This option will allow HOOPS to choose from one of the compression schemes offered by the underlying hardware drivers. This option can be ignored depending on the capabilities of the underlying hardware. The default will be 1, i.e. no compression.

texture options = (…) Options for the implicit texture created for the image. See Define_Texture() for the list of recognized options.

If you have a choice, (if it is possible to define the picture so) it is better to use lines, polygons, etc., rather than images, since that way 1) your picture’s appearance will be independent of the display device, and 2) you will have more ways to manipulate it. Images are appropriate when that’s the format of the data arriving from the outside world, or if you are drawing photograph-like pictures.

NOTES

If an image is not completely contained within the current window, it will be clipped appropriately.

You might find it convenient to set up a camera volume that matches the number of pixels on your screen. This will simplify aligning adjacent images exactly.

If you wish to transform an image (rotate, scale, etc.), any named image can be “painted” onto a shell or mesh face using a process called “texture mapping” (see Define_Texture() for details).

The double parameters are internally truncated to float. If you require extra precision, use this function’s double-precision variant, DInsert_Image.

Images are pixel-based in HOOPS and do not scale. In addition, image data does not currently obey the force grayscale driver option.

RESTRICTIONS

See also

HC_Set_Color_Map, HC_Edit_Image, HC_Move_Image, HC_Show_Image, HC_Modify_Color_Map, HC_Renumber_Key, HC_Set_Visibility, HC_Set_Driver_Options, HC_Define_Texture, HC_Set_Camera_By_Volume.

Parameters

x – - The x-coordinate of the center of the image.
y – - The y-coordinate of the center of the image.
z – - The z-coordinate of the center of the image.
format – - A description of how data in the data array is packed
width – - The number of columns of pixels in this image. Must be a positive number.
height – - The number of rows of pixels in this image. Must be a positive number.
data – - An array of bytes, packed in accordance with format, that describes the colors of each pixel in the image.

Returns

The key to the inserted geometry, or -1 if an error occurred.

Key HC_Insert_Compressed_Image(double x, double y, double z, char const *format, int width, int height, int size, void const *data)

Inserts a compressed pixel-based image in the HOOPS database.

The following choices for “format” are:

Supported Options:: discard, down-sample, grayscale, local, name, mapped 16, mapped 8, mapped, RGB, RGBA, size, jpg, tga, dxt1, dxt3, dxt5, compression quality, texture options,
DETAILS: This API has the same capabilities as Insert_Compressed_Image but additionally allows you to insert images which are already in a compressed form. JPEG, TGA and the DXT1, DXT3 and DXT5 formats are the only currently supported compression schemes.