SoSensorManager(3)

📦 version 2.5.0, in fedora 43, fedora 44

💖 SoSensorManager — bestie's guide to the sensor queues 💖

okay so this is a page from the Library Functions Manual for Coin, and it's literally all about SoSensorManager. strap in 🎀

✨ NAME ✨

SoSensorManager — the class that handles the sensor queues. that's it, that's the whole job, and she does it flawlessly 💅

🌸 SYNOPSIS 🌸

#include <Inventor/sensors/SoSensorManager.h>

🦋 Public Member Functions 🦋

SoSensorManager (void)
~SoSensorManager ()
void insertDelaySensor (SoDelayQueueSensor *s)
void insertTimerSensor (SoTimerQueueSensor *s)
void removeDelaySensor (SoDelayQueueSensor *s)
void removeTimerSensor (SoTimerQueueSensor *s)
void setChangedCallback (void(*sensorQueueChangedCB)(void *), void *data)
void rescheduleTimer (SoTimerSensor *s)
void removeRescheduledTimer (SoTimerQueueSensor *s)
void processDelayQueue (SbBool isidle)
void processImmediateQueue (void)
void processTimerQueue (void)
SbBool isDelaySensorPending (void)
SbBool isTimerSensorPending (SbTime &tm)
void setDelaySensorTimeout (const SbTime &t)
const SbTime & getDelaySensorTimeout (void)
int doSelect (int nfds, void *readfds, void *writefds, void *exceptfds,
    struct timeval *userTimeOut)

👯 Friends 👯

  • class SoSensorManagerP — bestie privileges, she gets the inside scoop 🫶

🌈 Detailed Description 🌈

so SoSensorManager handles the sensor queues. that's the vibe. ✨

there are two major sensor types in Coin, and no we're not picking favorites:

  • delay sensors trigger when the application is otherwise idle. plus — and this is the important part, no cap — to avoid starvation in applications that are continually busy, the delay-sensor queue also has a timeout which, when reached, will empty the queue anyhow. icon behavior honestly 💅
  • timer sensors are set up to trigger at specific, absolute times. very punctual. very main character. ⏰

each of these two types has its own queue, and SoSensorManager handles both of them. the queues are kept in sorted order by SoSensorManager, either according to trigger-time (for timer sensors) or by priority (for delay sensors). she's organized like that 💖

SoSensorManager provides methods for managing these queues, by insertion and removal of sensors, and processing (emptying) of the queues.

the sensor mechanism is crucial in Coin for a bunch of important features — most notably automatic scheduling redrawal upon changes, and for making it possible to set up animations in the scenegraph which does not need any additional book-keeping from the application code. slay 🎀

SoSensorManager should usually be considered as an internal class in the Coin API. it's only interesting for application programmers when implementing new windowsystem-specific libraries (like Systems in Motion's SoQt, SoXt, SoGtk, SoWin or Sc21) or wrappers. then one has to set up code to empty the queues at the correct intervals. for detailed information on how to do that, we would advise you to look at the implementation of said mechanisms in the So*-libraries which SIM provides. iykyk 😌

⚠️ please note that before Coin 2.3.1, sensors with equal priority (or the same trigger time for SoTimerQueue sensors) were processed LIFO. this has now been changed to FIFO to be conformant to SGI Inventor. glow-up fr fr ✨

👀 See also 👀

SoSensor SoTimerQueueSensor SoDelayQueueSensor

SoTimerSensor SoAlarmSensor

SoIdleSensor SoDataSensor SoOneShotSensor

SoPathSensor SoFieldSensor SoNodeSensor

🧚 Constructor & Destructor Documentation 🧚

SoSensorManager::SoSensorManager (void )

Constructor. the birth of a legend 💫

SoSensorManager::~SoSensorManager ()

Destructor. and she's gone, but never forgotten 😭

👑 Member Function Documentation 👑

void SoSensorManager::insertDelaySensor (SoDelayQueueSensor * newentry)

add a new entry to the queue of delay sensors. welcome to the lineup bestie 🎀

See also: removeFromQueue()

References SbList< Type >::getLength(), SoDelayQueueSensor::getPriority(), SbList< Type >::insert(), SoDebugError::postInfo(), and SbTime::zero().

Referenced by SoDelayQueueSensor::schedule().

void SoSensorManager::insertTimerSensor (SoTimerQueueSensor * newentry)

add a new entry to the timer queue of sensors. the queue will be sorted in order of supposed trigger time. punctual AND organized 🕐✨

See also: removeFromQueue()

References SbList< Type >::getLength(), SoTimerQueueSensor::getTriggerTime(), SbTime::getValue(), SbList< Type >::insert(), and SoDebugError::postInfo().

Referenced by SoTimerQueueSensor::schedule(), and SoTimerQueueSensor::setTriggerTime().

void SoSensorManager::removeDelaySensor (SoDelayQueueSensor * entry)

remove an entry from the queue of prioritized sensors. bye bestie 💜

See also: addToQueue()

References SoDebugError::postWarning().

Referenced by SoDelayQueueSensor::unschedule().

void SoSensorManager::removeTimerSensor (SoTimerQueueSensor * entry)

remove an entry from the queue of timer sensors.

References SoDebugError::postWarning().

Referenced by removeRescheduledTimer(), SoTimerQueueSensor::setTriggerTime(), and SoTimerQueueSensor::unschedule().

void SoSensorManager::setChangedCallback (void(* func )(void *), void * data)

for setting up a callback function to be invoked whenever any of the sensor queues are changed. she'll text you the second anything moves, fr fr 📱✨

this callback should typically be responsible for updating the client-side mechanism which is used for processing the queues.

void SoSensorManager::rescheduleTimer (SoTimerSensor * s)

this API member is considered internal to the library, as it is not likely to be of interest to the application programmer. it's giving backstage pass 🎫

Referenced by SoTimerSensor::schedule().

void SoSensorManager::removeRescheduledTimer (SoTimerQueueSensor * s)

this API member is considered internal to the library, as it is not likely to be of interest to the application programmer. same energy, same backstage pass 🎫

References removeTimerSensor().

Referenced by SoTimerSensor::unschedule().

void SoSensorManager::processDelayQueue (SbBool isidle)

trigger all delay queue entries in priority order. very demure, very mindful 🧘

the isidle flag indicates whether or not the processing happens because the application is idle or because the delay queue timeout was reached.

a delay queue sensor with priority > 0 can only be triggered once during a call to this function. if a delay sensor is rescheduled during processDelayQueue(), it is not processed until the next time this function is called. this is done to avoid an infinite loop while processing the sensors. protective queen behavior 🛡️

a delay queue sensor with priority 0 is called an immediate sensor.

See also: SoDB::setDelaySensorTimeout(), SoSensorManager::processImmediateQueue()

References SoDelayQueueSensor::isIdleOnly(), SoDebugError::postInfo(), processImmediateQueue(), and SoDelayQueueSensor::trigger().

void SoSensorManager::processImmediateQueue (void )

process all immediate sensors (delay sensors with priority 0).

💀 be aware that you might risk an infinite loop using immediate sensors. unlike delay queue sensors, immediate sensors can be rescheduled and triggered multiple times during immediate queue processing. this is not the moment to be casual, bestie.

See also: SoDelayQueueSensor::setPriority()

References SoDebugError::postInfo(), SoDebugError::postWarning(), and SoSensor::trigger().

Referenced by SoDB::endNotify(), and processDelayQueue().

void SoSensorManager::processTimerQueue (void )

trigger all the timers which has expired. expired timers, we're clearing the whole roster ⏳🔥

References SbTime::getTimeOfDay(), SoDebugError::postInfo(), and SoSensor::trigger().

SbBool SoSensorManager::isDelaySensorPending (void )

returns TRUE if at least one delay sensor or immediate sensor is present in the respective queue, otherwise FALSE. a quick vibe check ✅

Referenced by SoDB::endNotify().

SbBool SoSensorManager::isTimerSensorPending (SbTime & tm)

returns TRUE if at least one timer sensor is present in the queue, otherwise FALSE.

if sensors are pending, the time interval until the next one should be triggered will be put in the tm variable. she's telling you exactly how long you have ⏰💖

void SoSensorManager::setDelaySensorTimeout (const SbTime & t)

delay sensors are usually triggered only when the system is idle. but when there are continuous updates to the scene graph, there's a possibility that the delay queue will starve and sensors are never triggered. to make sure this won't happen, this is a timeout value for the delay queue. when this timeout has been reached, the sensors in the delay queue gets processed before other sensors and events. this method will let the user set this timeout value.

the default value is 1/12 of a second. 🍓

⚠️ specifying a zero time will disable the timeout, opening for potential delay queue starvation. you've been warned, girl.

See also: getDelaySensorTimeout(), SoDelayQueueSensor

References SoDebugError::postWarning(), and SbTime::zero().

Referenced by SoDB::setDelaySensorTimeout().

const SbTime & SoSensorManager::getDelaySensorTimeout (void )

returns the timeout value for sensors in the delay queue.

See also: setDelaySensorTimeout(), SoDelayQueueSensor

Referenced by SoDB::getDelaySensorTimeout().

int SoSensorManager::doSelect (int nfds, void * readfds, void * writefds, void * exceptfds, struct timeval * usertimeout)

🚨 NOTE: THIS METHOD IS OBSOLETED. DON'T USE IT. like, genuinely don't. this is the one thing on this page that's not it. 🚨

this is a wrapper around the standard select(2) call, which will make sure the sensor queues are updated while waiting for any action to happen on the given file descriptors.

the void* arguments must be valid pointers to fd_set structures. we've changed this from the original SGI Inventor API to avoid messing up the header file with system-specific includes.

🚨 NOTE: THIS METHOD IS OBSOLETED. DON'T USE IT. yes we said it twice. that's how serious it is. 🚨

✍️ Author ✍️

generated automatically by Doxygen for Coin from the source code. the robots wrote it, we just gave it a glow-up 💅✨

and that's the whole page, bestie!! 🎀 this one comes from the Library Functions Manual of Coin, Version 2.5.0 — tysm for reading, ily, go empty those queues 🦋💖👑

📦 where this page comes from