icetDrawFrame(3)

💅 icetDrawFrame — the IceT Reference, but make it make sense

okay bestie, so icetDrawFrame(3) is a whole IceT thing and I'm gonna walk you through it, no gatekeeping 💖

---

✨ NAME ✨

icetDrawFrame — renders and composites a frame 🎨

---

✨ Synopsis ✨

#include <IceT.h>

IceTImage icetDrawFrame(
                           const IceTDouble *   projection_matrix,
                           const IceTDouble *   modelview_matrix,
                           const IceTFloat *    background_color  );

---

✨ Description ✨

So basically, icetDrawFrame kicks off a frame draw using the transformation matrices you hand it (modelview and projection). Slay. But heads up — if you're using OpenGL, you probably want icetGLDrawFrame and the associated icetGLDrawCallback instead. Just saying. 👑

Before IceT can even render an image, three things have to be set up:

• the tiled display has to be defined (via icetAddTile) 🧩
• the drawing function has to be set (via icetDrawCallback) 🖌️
• the composite strategy has to be set (via icetStrategy) 🧠

You can optionally also set the single image sub-strategy with icetSingleImageStrategy. Fancy.

Also, and this part is not optional: every single process in the current IceT context has to call icetDrawFrame or it will never finish. Like, everyone. No one gets to sit this one out. 🫶

During compositing, IceT takes your projection_matrix and modelview_matrix, plus the bounds from the last call to icetBoundingBox or icetBoundingVertices, and figures out which pixels your local geometry projects onto. So if those matrices aren't the same ones you used while rendering, or if your bounds don't actually contain the geometry… IceT might clip your geometry in ways that will genuinely jump-scare you 😭. Not a vibe.

And another thing — IceT modifies projection_matrix for the drawing callback, to change the projection onto (or in between) tiles. So the move is: pass the projection_matrix you want into icetDrawFrame, then use the version that gets handed to the drawing callback. Periodt.

The background_color argument is exactly what it sounds like — the background color you want for the image 💅. It's an array of 4 floating point values: red, green, blue, and alpha, in that order, each in the range from 0.0 to 1.0.

When you're rendering with a depth buffer, the background color fills in the empty regions of images. When you're rendering with color blending, though, the background color gets switched to transparent black during rendering, so the background doesn't get blended over and over from different renderings. And if the ICET_CORRECT_COLORED_BACKGROUND feature is enabled, that background color gets blended back into the final composited image. ✨

---

✨ Return Value ✨

On each .igdisplay processdisplay process (as defined by icetAddTile), icetDrawFrame returns the fully composited image inside an IceTImage object 🎁. For any non-display process, the contents of that image are undefined — so don't go reading it, bestie, it's giving nothing.

If the ICET_COMPOSITE_ONE_BUFFER option is on and both a color and depth buffer are specified with icetSetColorFormat and icetSetDepthFormat, then the returned image might be missing the depth buffer. 👀 And the reasoning? Often you need both the color and depth buffer to composite the color buffer, but the composited depth buffer isn't needed at all. So compositing can save some time by not transferring depth information at that later stage of compositing. Iconic efficiency tbh.

The returned image uses memory buffers that get reclaimed the next time IceT renders or composites a frame. So do not use this image after the next call to icetDrawFrame — unless you changed the IceT context. 🚫

---

✨ Errors ✨

• ICET_INVALID_OPERATION — raised if the drawing callback hasn't been set. It can also be raised if icetDrawFrame gets called recursively, probably from inside the drawing callback. 💀 (recursion jump scare, fr fr)
• ICET_OUT_OF_MEMORY — not enough memory left to hold intermittent frame buffers and other temporary data. 😭

icetDrawFrame may also indirectly raise an error if there's an issue with the strategy or callback.

---

✨ Warnings ✨

None. 🎀 (yes, actually none, we're thriving)

---

✨ Bugs ✨

If you're compositing with color blending on, the image returned may have a black background instead of the background_color you asked for. 🙈 The fix is blending the returned image over the desired background yourself. Orrrr — this gets done for you automatically if the ICET_CORRECT_COLORED_BACKGROUND feature is enabled. 🦋

---

✨ Copyright ✨

Copyright (C)2003 Sandia Corporation

Under the terms of Contract DE-AC04-94AL85000 with Sandia Corporation, the U.S. Government retains certain rights in this software.

This source code is released under the New BSD License.

---

✨ See Also ✨

icetAddTile(3), icetBoundingBox(3), icetBoundingVertices(3), icetCompositeImage(3), icetDrawCallback(3), icetGLDrawFrame(3), icetSingleImageStrategy(3), icetStrategy(3)

---

and that's the whole page, bestie — you ate that 💅✨

this was the IceT Reference page, dated September 22, 2014 — go forth and composite, my main character 👑💖