occtl_viz.h

Go to the documentation of this file.

// Copyright (c) 2026 Capgemini Engineering Research and Development.
//
// This file is part of OCCT-Light software library.
//
// This library is free software; you can redistribute it and/or modify it under
// the terms of the GNU Affero General Public License version 3 as published
// by the Free Software Foundation, with an option to use any later version.
// Consult the file LICENSE_AGPL_30.txt included in OCCT-Light distribution
// for complete text of the license and disclaimer of any warranty.
//
// Alternatively, this file may be used under the terms of a commercial
// license or contractual agreement.
//
// SPDX-License-Identifier: AGPL-3.0-or-later
 
#ifndef OCCTL_VIZ_H
#define OCCTL_VIZ_H
 
#include <stddef.h>
#include <stdint.h>
 
#include "occtl_core.h"
#include "occtl_geom.h"
#include "occtl_topo.h"
 
#ifdef __cplusplus
extern "C"
{
#endif
 
typedef struct occtl_viz_driver occtl_viz_driver_t;
 
typedef struct occtl_viz_viewer occtl_viz_viewer_t;
 
typedef struct occtl_viz_view occtl_viz_view_t;
 
typedef struct occtl_viz_presentable occtl_viz_presentable_t;
 
typedef enum occtl_viz_display_mode
{
  OCCTL_VIZ_DISPLAY_WIREFRAME         = 0,  
  OCCTL_VIZ_DISPLAY_SHADED            = 1,  
  OCCTL_VIZ_DISPLAY_SHADED_WITH_EDGES = 10, 
  OCCTL_VIZ_DISPLAY_MESH_DEBUG        = 11, 
  OCCTL_VIZ_DISPLAY_RESERVED_FUTURE   = 0x7fffffff
} occtl_viz_display_mode_t;
 
typedef enum occtl_viz_selection_mode
{
  OCCTL_VIZ_SELECT_WHOLE           = 0,  
  OCCTL_VIZ_SELECT_FACE            = 1,  
  OCCTL_VIZ_SELECT_EDGE            = 2,  
  OCCTL_VIZ_SELECT_VERTEX          = 3,  
  OCCTL_VIZ_SELECT_WIRE            = 4,  
  OCCTL_VIZ_SELECT_SHELL           = 5,  
  OCCTL_VIZ_SELECT_SOLID           = 6,  
  OCCTL_VIZ_SELECT_COEDGE          = 7,  
  OCCTL_VIZ_SELECT_PRODUCT         = 8,  
  OCCTL_VIZ_SELECT_COMPOUND        = 9,  
  OCCTL_VIZ_SELECT_COMPSOLID       = 10, 
  OCCTL_VIZ_SELECT_RESERVED_FUTURE = 0x7fffffff
} occtl_viz_selection_mode_t;
 
typedef enum occtl_viz_standard_view
{
  OCCTL_VIZ_VIEW_FRONT           = 0, 
  OCCTL_VIZ_VIEW_BACK            = 1, 
  OCCTL_VIZ_VIEW_LEFT            = 2, 
  OCCTL_VIZ_VIEW_RIGHT           = 3, 
  OCCTL_VIZ_VIEW_TOP             = 4, 
  OCCTL_VIZ_VIEW_BOTTOM          = 5, 
  OCCTL_VIZ_VIEW_ISO             = 6, 
  OCCTL_VIZ_VIEW_RESERVED_FUTURE = 0x7fffffff
} occtl_viz_standard_view_t;
 
#define OCCTL_VIZ_DRIVER_OPTIONS_VERSION_1 1u
#define OCCTL_VIZ_VIEW_OPTIONS_VERSION_1 1u
 
typedef struct occtl_viz_driver_options
{
  uint32_t    struct_version; 
  const void* p_next;         
  int32_t     enable_vbo;     
  int32_t     enable_vsync;   
} occtl_viz_driver_options_t;
 
#define OCCTL_VIZ_DRIVER_OPTIONS_INIT {OCCTL_VIZ_DRIVER_OPTIONS_VERSION_1, NULL, 1, 1}
 
typedef struct occtl_viz_view_options
{
  uint32_t    struct_version; 
  const void* p_next;         
  int32_t     width;          
  int32_t     height;         
  void*       native_handle;  
  int32_t     offscreen;      
} occtl_viz_view_options_t;
 
#define OCCTL_VIZ_VIEW_OPTIONS_INIT {OCCTL_VIZ_VIEW_OPTIONS_VERSION_1, NULL, 640, 480, NULL, 1}
 
typedef struct occtl_viz_camera
{
  occtl_point3_t  eye;    
  occtl_point3_t  center; 
  occtl_vector3_t up;     
} occtl_viz_camera_t;
 
#define OCCTL_VIZ_PICK_RESULT_VERSION_1 1u
 
typedef struct occtl_viz_pick_result
{
  uint32_t                   struct_version;  
  const void*                p_next;          
  occtl_uid_t                uid;             
  occtl_node_id_t            node;            
  occtl_ref_id_t             ref;             
  occtl_viz_selection_mode_t selection_mode;  
  occtl_transform_t          usage_transform; 
} occtl_viz_pick_result_t;
 
#define OCCTL_VIZ_PICK_RESULT_INIT                                                                 \
  {                                                                                                \
    OCCTL_VIZ_PICK_RESULT_VERSION_1, NULL, OCCTL_UID_INVALID, OCCTL_NODE_ID_INVALID,               \
      OCCTL_REF_ID_INVALID, OCCTL_VIZ_SELECT_WHOLE,                                                \
    {{1.0, 0.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 0.0, 1.0, 0.0}}                                 \
  }
 
OCCTL_API void OCCTL_CALL occtl_viz_driver_options_init(occtl_viz_driver_options_t* options);
 
OCCTL_API void OCCTL_CALL occtl_viz_view_options_init(occtl_viz_view_options_t* options);
 
OCCTL_API void OCCTL_CALL occtl_viz_pick_result_init(occtl_viz_pick_result_t* pick);
 
OCCTL_API occtl_status_t OCCTL_CALL
  occtl_viz_driver_create(const occtl_viz_driver_options_t* options,
                          occtl_viz_driver_t**              out_driver);
 
OCCTL_API void OCCTL_CALL occtl_viz_driver_free(occtl_viz_driver_t* driver);
 
OCCTL_API occtl_status_t OCCTL_CALL occtl_viz_viewer_create(occtl_viz_driver_t*  driver,
                                                            occtl_viz_viewer_t** out_viewer);
 
OCCTL_API void OCCTL_CALL occtl_viz_viewer_free(occtl_viz_viewer_t* viewer);
 
OCCTL_API occtl_status_t OCCTL_CALL occtl_viz_view_create(occtl_viz_viewer_t*             viewer,
                                                          const occtl_viz_view_options_t* options,
                                                          occtl_viz_view_t**              out_view);
 
OCCTL_API void OCCTL_CALL occtl_viz_view_free(occtl_viz_view_t* view);
 
OCCTL_API occtl_status_t OCCTL_CALL
  occtl_viz_presentable_create(occtl_viz_viewer_t*       viewer,
                               occtl_graph_t*            graph,
                               occtl_node_id_t           root,
                               occtl_viz_presentable_t** out_presentable);
 
OCCTL_API void OCCTL_CALL occtl_viz_presentable_free(occtl_viz_presentable_t* presentable);
 
OCCTL_API occtl_status_t OCCTL_CALL
  occtl_viz_presentable_set_display_mode(occtl_viz_presentable_t* presentable,
                                         occtl_viz_display_mode_t mode);
 
OCCTL_API occtl_status_t OCCTL_CALL
  occtl_viz_presentable_synchronize(occtl_viz_presentable_t* presentable, int32_t* out_has_changed);
 
OCCTL_API occtl_status_t OCCTL_CALL
  occtl_viz_presentable_invalidate(occtl_viz_presentable_t* presentable);
 
OCCTL_API occtl_status_t OCCTL_CALL
  occtl_viz_presentable_set_visible_nodes(occtl_viz_presentable_t* presentable,
                                          const occtl_node_id_t*   nodes,
                                          size_t                   n_nodes);
 
OCCTL_API occtl_status_t OCCTL_CALL
  occtl_viz_presentable_clear_visible_nodes(occtl_viz_presentable_t* presentable);
 
OCCTL_API occtl_status_t OCCTL_CALL occtl_viz_view_display(occtl_viz_view_t*        view,
                                                           occtl_viz_presentable_t* presentable);
 
OCCTL_API occtl_status_t OCCTL_CALL occtl_viz_view_erase(occtl_viz_view_t*        view,
                                                         occtl_viz_presentable_t* presentable);
 
OCCTL_API occtl_status_t OCCTL_CALL occtl_viz_view_resize(occtl_viz_view_t* view,
                                                          int32_t           width,
                                                          int32_t           height);
 
OCCTL_API occtl_status_t OCCTL_CALL occtl_viz_view_redraw(occtl_viz_view_t* view);
 
OCCTL_API occtl_status_t OCCTL_CALL occtl_viz_view_fit_all(occtl_viz_view_t* view);
 
OCCTL_API occtl_status_t OCCTL_CALL occtl_viz_view_set_background(occtl_viz_view_t*  view,
                                                                  occtl_color_rgba_t color);
 
OCCTL_API occtl_status_t OCCTL_CALL occtl_viz_view_set_camera(occtl_viz_view_t*         view,
                                                              const occtl_viz_camera_t* camera);
 
OCCTL_API occtl_status_t OCCTL_CALL occtl_viz_view_get_camera(const occtl_viz_view_t* view,
                                                              occtl_viz_camera_t*     out_camera);
 
OCCTL_API occtl_status_t OCCTL_CALL
  occtl_viz_view_set_standard_view(occtl_viz_view_t* view, occtl_viz_standard_view_t standard_view);
 
OCCTL_API occtl_status_t OCCTL_CALL occtl_viz_view_pan(occtl_viz_view_t* view,
                                                       int32_t           dx,
                                                       int32_t           dy);
 
OCCTL_API occtl_status_t OCCTL_CALL
  occtl_viz_view_zoom(occtl_viz_view_t* view, int32_t x1, int32_t y1, int32_t x2, int32_t y2);
 
OCCTL_API occtl_status_t OCCTL_CALL occtl_viz_view_orbit_start(occtl_viz_view_t* view,
                                                               int32_t           x,
                                                               int32_t           y);
 
OCCTL_API occtl_status_t OCCTL_CALL occtl_viz_view_orbit_update(occtl_viz_view_t* view,
                                                                int32_t           x,
                                                                int32_t           y);
 
OCCTL_API occtl_status_t OCCTL_CALL
  occtl_viz_view_activate_selection(occtl_viz_view_t*          view,
                                    occtl_viz_presentable_t*   presentable,
                                    occtl_viz_selection_mode_t mode);
 
OCCTL_API occtl_status_t OCCTL_CALL occtl_viz_view_pick(occtl_viz_view_t*        view,
                                                        int32_t                  x,
                                                        int32_t                  y,
                                                        int32_t                  select,
                                                        occtl_viz_pick_result_t* out_pick);
 
OCCTL_API occtl_status_t OCCTL_CALL occtl_viz_view_read_pixels_rgba(occtl_viz_view_t* view,
                                                                    uint8_t*          out_rgba,
                                                                    size_t            cap,
                                                                    size_t*           out_count);
 
OCCTL_API occtl_status_t OCCTL_CALL occtl_viz_view_dump_image(occtl_viz_view_t* view,
                                                              const char*       path);
 
#ifdef __cplusplus
}
#endif
 
#endif /* OCCTL_VIZ_H */