icetGLDrawFrame(3)

✨ icetGLDrawFrame(3) ✨

okay so bestie, we're in the IceT Reference today and this one is literally the moment everything pays off 💅 it's icetGLDrawFrame, and it does the whole render + composite a frame using OpenGL thing. she's the main character, fr fr.

---

🌸 NAME 🌸

icetGLDrawFrame — renders and composites a frame using OpenGL 🎀

---

✨ Synopsis ✨

#include <IceTGL.h>

void icetGLDrawFrame( void );

that's it. no args, no nothing. she takes zero notes and gives you a whole picture 🫶

---

💖 Description 💖

So basically: this kicks off a frame draw using the current OpenGL transformation matrices — both the modelview and the projection one. 👑

But before IceT can even think about rendering an image, you gotta have your ducks in a row, okay? Here's the checklist bestie:

• the tiled display has to be defined (that's icetAddTile)
• the drawing function has to be set (that's icetGLDrawCallback)
• the composite strategy must be set (that's icetStrategy)
• and optionally, the single image sub-strategy can be set too (that's icetSingleImageStrategy)

no cap: every single process in the current IceT context has to call icetGLDrawFrame for it to actually complete. it's giving group project where everyone must show up. 😭

Now, about those matrices — the OpenGL projection matrix and the modelview matrix have to be set with glLoadMatrix or a whole bunch of other functions. Same energy for the OpenGL background color: that one gets set with glClearColor. IceT uses the matrices to figure out which pixels need rendering and compositing, and she will also modify the projection matrix to project onto (or in between) tiles. iconic behavior honestly ✨

If ICET_GL_DISPLAY is enabled, then the fully composited image gets written back to the OpenGL framebuffer for display. And heads up — it's the application's responsibility to synchronize the processes and swap front and back buffers. not IceT's job, that one's on you bestie 🫡

If the OpenGL background color is set to anything other than black, you should also enable ICET_GL_DISPLAY_COLORED_BACKGROUND. Here's the tea though: displaying with ICET_GL_DISPLAY_COLORED_BACKGROUND disabled may be slightly faster (depends on your graphics hardware, ymmv) but it can result in black rectangles in the background. so... pick your poison 💀

If ICET_GL_DISPLAY_INFLATE is enabled and the size of the renderable window (which is determined by the current OpenGL viewport) is greater than that of the tile being displayed, then the image will first be "inflated" to the size of the actual display. That inflation gets assisted by texture hardware if ICET_GL_DISPLAY_INFLATE_WITH_HARDWARE is on. 🔥

And if ICET_GL_DISPLAY_INFLATE is disabled, the image is just drawn at its original resolution, chilling in the lower left corner of the display. humble. grounded. 🌱

⚠️ real talk: the image remaining in the frame buffer is undefined if ICET_GL_DISPLAY is disabled, or if the process is not displaying a tile. undefined means undefined, don't come for me 😭

---

💅 Errors 💅

• ICET_INVALID_OPERATION — raised if icetGLInitialize has not been called, or if the drawing callback has not been set. Also can pop off if icetGLDrawFrame is called recursively, probably from within the drawing callback. (so don't do that 🫠)
• ICET_OUT_OF_MEMORY — not enough memory left to hold intermittent frame buffers and other temporary data. she's hungry and there's no snacks left 😭

also, icetGLDrawFrame may indirectly raise an error if there's an issue with the strategy or the callback. just so you know 👀

---

🙈 Warnings 🙈

None. not a single one. she's well behaved. ✨

---

🐛 Bugs 🐛

okay so there IS one thing: if you're compositing with color blending on, the image returned may have a black background instead of the background_color you requested. rude, honestly. 😤

The fix? Blend the returned image over the desired background yourself. And guess what — that'll be done for you automatically if ICET_CORRECT_COLORED_BACKGROUND is on. slay 🎀

---

👑 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)
• icetDrawFrame(3)
• icetGLDrawCallback(3)
• icetSingleImageStrategy(3)
• icetStrategy(3)

---

and that's the whole page bestie!! 🫶 this was the IceT Reference version from September 26, 2014 — go forth and composite, you absolute icon 💖✨🌸