Skip to content

Developer checklists

Implementing a new visual

  • Determine the graphics you'll be using, and the list of source and props
  • builtin_visuals.h:
    • Make sure the DvzVisualType enum exists, or create a new one
  • visuals.h:
    • Check that all prop types exist, otherwise add them
  • builtin_visuals.c:
    • Make a new section for the visual code
    • Write the main visual function
      • Specify the graphics pipeline(s)
      • Specify the sources:
        • Vertex buffer
        • Index buffer (optional)
        • Param buffer (optional)
        • Textures (optional)
      • Specify the props
        • The cast and copy spec are not mandatory if there is a custom baking callback function
        • Note that the special POS prop is DVEC3 and is typically cast to VEC3, but only after baking and panel transform
        • Add a length prop if there are multiple objects
        • Add the common props
        • Add the param props
        • Specify the props that need DPI scaling
      • Specify the baking callback function (optional)
    • Write the baking callback function
      • Take DPI scaling into account for props that require it
    • Add a new switch case in dvz_visual_builtin()
  • test_builtin_visuals.h:
    • Add a new visual test declaration
  • test_builtin_visuals.c:
    • Write the body of the test function
  • main.c:
    • Add the new test to the list of test functions
  • Test the new visual without interactivity and save a visual screenshot
  • Add a section in the visual reference docs/reference/visuals.md, document the props, sources, etc.

Implementing a new graphics

  • graphics.h:
    • Add the typedef of the vertex, item, params structures
    • Add new section and structs for vertex, item, params structures
      • Make sure all fields in the params struct have a byte size that is not 3 or divisible by 3
    • Put comments after each struct field (used by automatic documentation generator)
  • vklite.h:
    • Make sure the DvzGraphicsType enum exists, or create a new one
  • Shaders: graphics_xxx.vert|frag:
    • Don't forget to import common.glsl in all shaders
    • The first user binding should be params, should match exactly the struct
    • The next bindings should be numbered with USER_BINDING+1 etc
    • The body of the main fragment shader function should always begin with CLIP
  • graphics.c:
    • Add new section, with _graphics_xxx() and _graphics_xxx_callback() if there is a non-default graphics callback function
    • Write the main graphics function
      • Specify the shaders
      • Specify the primitive type
      • Specify the vertex attributes, should match the vertex shader
      • Add the common slots
      • Add slots for params/textures
      • Specify the graphics callback function
    • (optional) Write the graphics callback function
      • This function is called when a new item is added to the graphics. What an "item" is is up to the create of a graphics. It's typically the smallest bit of data that has a meaning in the context of the graphics. The graphics callback is mostly used for pre-upload CPU-side "triangulation" of the data, so that the visuals that reuse this graphics don't have to know the details of the triangulation.
    • Add the switch case in dvz_graphics_builtin()
  • test_graphics.h:
    • Add the new graphics test declaration
  • test_graphics.c:
    • Write the body of the test function
    • Set to save the screenshot with the graphics name
  • main.c:
    • Add the new test to the list of test functions
  • Test the graphics without interactivity and save the graphics screenshot
  • Add graphics section in docs/reference/graphics.md

Implementing a new GUI control

  • controls.h:
    • Add the DvzGuiControlType enum
    • If there are control parameters:
      • Create a DvzGuiControlXXX typedef struct
      • Declare the struct
      • Add it to the DvzGuiControlUnion union
    • Declare the new dvz_gui_xxx() function, and write the docstring
  • controls.c:
    • Write the body of the dvz_gui_xxx() function
  • gui.cpp:
    • In _show_control(), add a new switch case and call _show_xxx()
    • Implement _show_xxx()
  • test_canvas.c:
    • In test_canvas_gui_1(), add the new control with a call to dvz_gui_xxx()
    • Try the next test with DVZ_INTERACT=1 ./manage.sh test test_canvas_gui_1
  • cydatoviz.pxd:
    • After # FUNCTION START, add void dvz_gui_xxx() (no need to put the arguments, the Cython bindings generator will do it automatically)
  • pydatoviz.pyx:
    • Update the _CONTROLS dictionary
    • In Gui.control(), add a new if statement and make the binding
    • In _get_ev_args(), add a new if statement and make the callback argument binding
    • In GuiControl.set() , add a new if statement and set the control value
  • Run ./manage.sh cython
  • Test in a Python example gui.control('xxx', 'name', ...)