vpGetTimer(3)

✨ vpGetTimer ✨

okay bestie, so this is a page from the Library Functions Manual about vpGetTimer(3) — aka the VolPack interval timer facility 💅 it's how you clock how long the library is spending doing stuff. let's get into it.

---

🎀 NAME 🎀

vpGetTimer, vpClearTimer — interval timer facility ⏱️✨

---

🦋 SYNOPSIS 🦋

#include <volpack.h>

vpResult
vpGetTimer(vpc, option, iptr)
    vpContext *vpc;
    int option;
    int *iptr;;

vpResult
vpClearTimer(vpc, option)
    vpContext *vpc;
    int option;

not me pointing out that stray double semicolon on int *iptr;; — it's literally in the original, i am NOT touching it, character for character, periodt 💀

---

🌸 ARGUMENTS 🌸

• vpc — the VolPack context, the one you got from vpCreateContext. your main character object fr 🫶
• option — a constant that picks out which particular timer you're talking about.
• iptr — the location where the timer value gets stored. it's a pointer, so it's writing into your int, no cap.

---

👑 DESCRIPTION 👑

so these functions are for measuring the performance of the VolPack library. performance girlies rise 🧚

to use them, the library has to be compiled with a special flag, and you've got options:

• -DHAVE_LORES_TIMER — for machines that support the gettimeofday C library call
• -DHAVE_HIRES_TIMER — for SGI machines that support high-resolution memory-mapped I/O timers
  • and on a Challenge or ONYX, you also have to specify -DHAVE_64BIT_TIMER. yes, additionally. both. don't forget the second one bestie 😭

if one of these flags is specified at compile time, then VolPack keeps a whole table recording the accumulated time spent in various operations. it's giving receipts 📋

⚠️ heads up: some of these operations can only be timed with a high-resolution timer. if a low resolution timer is specified at compile time, those time values will not be recorded and will appear to be zero. so don't be out here confused when your numbers are just 0, it's not you, it's the timer resolution 💀

💖 vpGetTimer 💖

vpGetTimer retrieves the accumulated time for a particular operation. the option argument says which operation:

• VPTIMER_SHADE — times the routine that computes the contents of the shading lookup table.
• VPTIMER_RENDER — times the routine that renders a volume. this one is the big one, it includes VPTIMER_CLSFY_OCTREE, VPTIMER_COMPOSITE, VPTIMER_DEPTHCUE, and VPTIMER_WARP. nested timers, we love a hierarchy 💅
• VPTIMER_COMPOSITE — times the routine that computes the intermediate image from the volume. includes VPTIMER_CLEAR, VPTIMER_TRAVERSE_OCTREE, VPTIMER_ERT, VPTIMER_TRAVERSE_RUNS, and VPTIMER_PROCESS_VOXELS. another little family 🌈
• VPTIMER_DEPTHCUE — times the routine that performs the depth cueing fixup on the intermediate image.
• VPTIMER_WARP — times the routine that warps the intermediate image into the final image. glow up stage ✨
• VPTIMER_TRAVERSE_RUNS — times the portion of the compositing routine devoted to traversing the volume data structures.
• VPTIMER_PROCESS_VOXELS — times the portion of the compositing routine devoted to compositing voxels into the intermediate image.
• VPTIMER_ERT — times the early-ray termination checks during compositing.
• VPTIMER_CLSFY_OCTREE — times the octree classification stage.
• VPTIMER_TRAVERSE_OCTREE — times the portion of the compositing routine devoted to traversing the octree.
• VPTIMER_CLEAR — times the routine that clears the intermediate image at the beginning of compositing.

the routine stores the accumulated time since the last call to vpClearTimer (or since the beginning of the program, if you never called it) in the location specified by iptr. the units of the value are microseconds. tiny units, big drama ⏱️

💜 vpClearTimer 💜

vpClearTimer sets the specified timer value back to zero. reset button, fresh start, new era 🎀

---

🔥 ERRORS 🔥

the normal return value is VP_OK. the following error return value is possible:

• VPERROR_BAD_OPTION — the option argument is invalid. you passed something that isn't a real timer, bestie, and it said no 🙈

---

🌟 SEE ALSO 🌟

VolPack(3), vpCreateContext(3)

---

and that's the whole page!! this one comes to you from VolPack, and yes the page itself is literally called vpGetTimer(3) — mwah, go measure something, ily, bye 🫶💖✨