SOXTRENDERAREA(3iv)

📦 version 2.1.6.1, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 SoXtRenderArea 💖

okay bestie, welcome to SoXtRenderArea(3IV) — the section 3 manual page for the Xt Component that renders Inventor scene graphs. grab a boba, this one's a whole journey 🧋✨

🌸 NAME 🌸

SoXtRenderArea — the Xt Component for rendering Inventor scene graphs, and she is booked and busy 💅

🦋 INHERITS FROM 🦋

SoXtComponent > SoXtGLWidget > SoXtRenderArea

so like, she comes from a whole distinguished bloodline, iykyk 👑

✨ SYNOPSIS ✨

first things first, include her:

#include <Inventor/Xt/SoXtRenderArea.h>

and here's the callback type she rolls with:

typedef SbBool      SoXtRenderAreaEventCB(void *userData, XAnyEvent *anyevent)

🎀 Methods from class SoXtRenderArea

these are HER methods, her own little icon era:

SoXtRenderArea(Widget parent = NULL, const char *name = NULL, SbBool buildInsideParent = TRUE, SbBool getMouseInput = TRUE, SbBool getKeyboardInput = TRUE)
~SoXtRenderArea()
virtual void             setSceneGraph(SoNode *newScene)
virtual SoNode *         getSceneGraph()
void                     setOverlaySceneGraph(SoNode *newScene)
SoNode *                 getOverlaySceneGraph()
void                     registerDevice(SoXtDevice *)
void                     unregisterDevice(SoXtDevice *)
void                     setBackgroundColor(const SbColor &c)
const SbColor &          getBackgroundColor() const
void                     setBackgroundIndex(int index)
int                      getBackgroundIndex() const
void                     setOverlayBackgroundIndex(int index)
int                      getOverlayBackgroundIndex() const
void                     setColorMap(int startIndex, int num, const SbColor *colors)
void                     setOverlayColorMap(int startIndex, int num, const SbColor *colors)
void                     setViewportRegion(const SbViewportRegion &newRegion)
const SbViewportRegion & getViewportRegion() const
void                     setTransparencyType(SoGLRenderAction::TransparencyType type)
SoGLRenderAction::TransparencyType getTransparencyType() const
void                     setAntialiasing(SbBool smoothing, int numPasses)
void                     getAntialiasing(SbBool &smoothing, int &numPasses) const
void                     setClearBeforeRender(SbBool trueOrFalse)
SbBool                   isClearBeforeRender() const
void                     setClearBeforeOverlayRender(SbBool trueOrFalse)
SbBool                   isClearBeforeOverlayRender() const
void                     setAutoRedraw(SbBool trueOrFalse)
SbBool                   isAutoRedraw() const
void                     setRedrawPriority(uint32_t priority)
uint32_t                 getRedrawPriority() const
static uint32_t          getDefaultRedrawPriority()
void                     render()
void                     renderOverlay()
void                     scheduleRedraw()
void                     scheduleOverlayRedraw()
void                     redrawOnSelectionChange(SoSelection *s)
void                     redrawOverlayOnSelectionChange(SoSelection *s)
void                     setEventCallback(SoXtRenderAreaEventCB *fcn, void *userData = NULL)
void                     setGLRenderAction(SoGLRenderAction *ra)
SoGLRenderAction *       getGLRenderAction() const
void                     setOverlayGLRenderAction(SoGLRenderAction *ra)
SoGLRenderAction *       getOverlayGLRenderAction() const
void                     setSceneManager(SoSceneManager *sm)
SoSceneManager *         getSceneManager() const
void                     setOverlaySceneManager(SoSceneManager *sm)
SoSceneManager *         getOverlaySceneManager() const

🫶 Methods from class SoXtGLWidget

the inherited ones, still iconic:

void                setBorder(SbBool onOrOff)
SbBool              isBorder() const
virtual void        setDoubleBuffer(SbBool onOrOff)
SbBool              isDoubleBuffer()
Window              getNormalWindow()
Window              getOverlayWindow()
GLXContext          getNormalContext()
GLXContext          getOverlayContext()
Widget              getNormalWidget()
Widget              getOverlayWidget()
virtual void        setNormalVisual(XVisualInfo *vis)
XVisualInfo *       getNormalVisual()
virtual void        setOverlayVisual(XVisualInfo *vis)
XVisualInfo *       getOverlayVisual()
void                setDrawToFrontBufferEnable(SbBool enableFlag)
SbBool              isDrawToFrontBufferEnable() const

💜 Methods from class SoXtComponent

and the grandma-of-the-house methods, slaying since forever:

virtual void            show()
virtual void            hide()
SbBool                  isVisible()
Widget                  getWidget() const
SbBool                  isTopLevelShell() const
Widget                  getShellWidget() const
Widget                  getParentWidget() const
void                    setSize(const SbVec2s &size)
SbVec2s                 getSize()
Display *               getDisplay()
void                    setTitle(const char *newTitle)
const char *            getTitle() const
void                    setIconTitle(const char *newIconTitle)
const char *            getIconTitle() const
void                    setWindowCloseCallback(SoXtComponentCB *func, void *data = NULL)
static SoXtComponent *  getComponent(Widget w)
const char *            getWidgetName() const
const char *            getClassName() const

🌈 DESCRIPTION 🌈

okay so here's the whole vibe. This class gives you Inventor rendering and event handling living inside a GLX Motif widget. There's a routine to specify the scene to render — cute, simple, we love her. And the scene gets rendered automatically whenever anything under it changes, because a data sensor is attached to the root of the scene. That's the default, periodt. The only exception? If you explicitly tell her not to do that, i.e. manual redraws. Then she minds her business and waits for you 🙈

You can also set Inventor rendering attributes — stuff like the transparency type, antialiasing on or off, etc. And under the hood, this class employs an SoSceneManager to manage rendering and event handling, because she's organized like that 💅

💫 how events get handled, bestie (this part matters)

X events that happen in the render area can be handled by the application, by the viewer (if this is really a viewer), or by the nodes in the scene graph. Three candidates, one event. Here's the order of operations, no skipping:

  1. When an event occurs, it is first passed to the application event callback function registered with the setEventCallback() method on SoXtRenderArea.
  2. If this function does not exist, or it returns FALSE, the X event is either used directly by the viewer or translated to an SoEvent for further scene graph processing.
  3. If the viewer does not handle the event, and an overlay scene graph exists, the SoEvent is sent to that scene graph by way of an SoHandleEventAction.
  4. If no node in the overlay scene graph handles the event — meaning nobody calls setHandled() on the SoHandleEventAction — the SoEvent is passed to the normal scene graph in the same manner.
so basically: app first, then viewer, then overlay graph, then normal graph. the event is on a whole relay race and somebody better catch it 🏃‍♀️🔥

that's part 1, my love — there's more coming so don't you dare close the tab 🫶✨

✨ METHODS ✨

Okay bestie, this is the part where we meet the whole friend group 💅 every single method this class has. Buckle up, there's a lot of them, and they're all lowkey iconic.

SoXtRenderArea(Widget parent = NULL, const char *name = NULL,
               SbBool buildInsideParent = TRUE,
               SbBool getMouseInput = TRUE,
               SbBool getKeyboardInput = TRUE)
~SoXtRenderArea()
  • The constructor 🎀 it takes the args that tell it whether to register the mouse and keyboard devices by default — those would be SoXtMouse and SoXtKeyboard. So you're basically saying "hey, do you want to auto-subscribe to mouse and keyboard or not" right at birth.
  • virtual void setSceneGraph(SoNode *newScene)
  • virtual SoNode * getSceneGraph() — set/get the scene graph that gets rendered in this component's window. That's the whole point of the thing, fr fr.
  • void setOverlaySceneGraph(SoNode *newScene)
  • SoNode * getOverlaySceneGraph() — sets/gets the scene graph you want rendered in the overlay bit planes. Fancy ✨
Heads up: the overlay bit planes are in color index mode, single buffer, with a limited number of colors, so the user should keep overlay rendering to simple objects only. No cap. Typically, rendering in color index mode is done using the SoColorIndex node with a SoLightModel set to BASE_COLOR.
  • void registerDevice(SoXtDevice *)
  • void unregisterDevice(SoXtDevice *) — register/unregister your interest in devices 🫶. Once a device is registered, events from it get processed by the render area and passed into the scene graph. Events from unregistered devices? Ignored. Not even looked at. 💀
  • void setBackgroundColor(const SbColor &c)
  • const SbColor & getBackgroundColor() const — set/get the background color for this window. Default is black, (0,0,0).
  • void setBackgroundIndex(int index)
  • int getBackgroundIndex() const — sets/gets the window background color when you're in color index mode. Defaults to black, which is index 0.
  • void setOverlayBackgroundIndex(int index)
  • int getOverlayBackgroundIndex() const — sets/gets the overlay window background color index. Defaults to 0, the clear color.
  • void setColorMap(int startIndex, int num, const SbColor *colors) — sets the colors to use when displaying in color index mode. This loads the color map with the given colors, starting at the index you pass. 🌈
  • void setOverlayColorMap(int startIndex, int num, const SbColor *colors) — same energy but for the overlay bit planes. Loads the color map with the given colors at the starting index.
  • void setViewportRegion(const SbViewportRegion &newRegion)
  • const SbViewportRegion & getViewportRegion() const — sets/gets the current viewport region used for rendering.
  • void setTransparencyType(SoGLRenderAction::TransparencyType type)
  • SoGLRenderAction::TransparencyType getTransparencyType() const — set/get the quality level for rendering transparent objects. Peep SoGLRenderAction for the possible transparency types 👑
  • void setAntialiasing(SbBool smoothing, int numPasses)
  • void getAntialiasing(SbBool &smoothing, int &numPasses) const — set/get the antialiasing for rendering. There are two kinds available: smoothing and multipass antialiasing.
    • If smoothing is set to TRUE, smoothing is on. Smoothing uses OpenGL's line- and point-smoothing features to give you cheap antialiasing of lines and points.
    • The value of numPasses controls multipass antialiasing. Every time a render action is applied, Inventor renders the scene numPasses times from slightly different camera positions and averages the results 🎀 numPasses can be from one to 255, inclusive. Setting numPasses to one disables multipass antialiasing.
    • You can use either, both, or neither of these techniques. By default, both smoothing and multipass antialiasing are disabled.
  • void setClearBeforeRender(SbBool trueOrFalse)
  • SbBool isClearBeforeRender() const — enable/prevent the window from being cleared before a rendering starts. Default is clear TRUE. This is genuinely useful for limiting flickering when you're doing single buffering and the geometry covers the entire window — it's used in the material editor, iykyk.
  • void setClearBeforeOverlayRender(SbBool trueOrFalse)
  • SbBool isClearBeforeOverlayRender() const — enable/prevent the overlay window from being cleared before a rendering starts. Default is clear TRUE.
  • void setAutoRedraw(SbBool trueOrFalse)
  • SbBool isAutoRedraw() const — the render area automatically redraws whenever something in the scene graph changes. Passing FALSE disables that feature. Main character energy only when you want it ✨
  • void setRedrawPriority(uint32_t priority)
  • uint32_t getRedrawPriority() const
  • static uint32_t getDefaultRedrawPriority() — sets/gets the priority of the redraw sensor, and grabs the default priority number. 🦋
  • void render()
  • void renderOverlay() — calling this forces the render area to be redrawn right now. You don't need to call it if auto redraw is enabled (and it's enabled by default), so bestie, usually you can just chill.
  • void scheduleRedraw()
  • void scheduleOverlayRedraw() — schedule a redraw to happen sometime soon instead of immediately. This is the move when you want to compress multiple redraws into one, chef's kiss 😭
  • void redrawOnSelectionChange(SoSelection *s)
  • void redrawOverlayOnSelectionChange(SoSelection *s) — a convenience method: call it and this render area redraws whenever the selection list changes in the node you passed. Super useful if you're using a highlight render action like SoBoxHighlightRenderAction, so it correctly renders every time the selection changes. Pass NULL to turn this off.
  • void setEventCallback(SoXtRenderAreaEventCB *fcn, void *userData = NULL) — X events that happen in the render area window are either handled directly by the viewer (when this is really a viewer) or automatically translated into SoEvents and passed into the scene graph via the SoHandleEventAction, so live scene graph objects can handle them (when viewers are not in viewing mode). This method lets the application register a callback for handling events in the window instead of sending them to the viewers or down the graph. The callback gets passed the X event, and should return TRUE if it handled it. If the callback returns FALSE, then the render area handles the event itself. Teamwork 💖
  • void setGLRenderAction(SoGLRenderAction *ra)
  • SoGLRenderAction * getGLRenderAction() const — sets/gets the GL render action to use. This is how you set selection highlighting with the SoBoxHighlightRenderAction and SoLineHighlightRenderAction classes 🔥
  • void setOverlayGLRenderAction(SoGLRenderAction *ra)
  • SoGLRenderAction * getOverlayGLRenderAction() const — sets/gets the GL render action for the overlay window.
  • void setSceneManager(SoSceneManager *sm)
  • SoSceneManager * getSceneManager() const
  • void setOverlaySceneManager(SoSceneManager *sm)
  • SoSceneManager * getOverlaySceneManager() const — sets/gets the normal and overlay plane scene managers.
Little note bestie: for convenience, most of the SoSceneManager methods have already been added to this class. So they're kind of just... here now. You're welcome 💅

🌸 RESOURCES 🌸

One singular X resource and she's doing her best:

  • *SoXtRenderArea*BackgroundColor: black (color name or hex value) — yep, it takes a color name or a hex value. Versatile queen.

👑 SEE ALSO 👑

Go check out the rest of the fam:

  • SoXtGLWidget
  • SoXtComponent
  • SoXtViewer
  • SoSceneManager
  • SoBoxHighlightRenderAction
  • SoLineHighlightRenderAction

And that's the whole page, bestie 🫶 this is SoXtRenderArea(3IV) — that's the source and version tag — and the date slot down there is just... blank. Mysterious. Enigmatic. We stan a timeless queen ✨💜

📦 where this page comes from