icetEnable(3)

💖 icetEnable(3) — the IceT Reference glow-up 💖

okay bestie, welcome to the icetEnable / icetDisable page of the IceT Reference manual. this is the one where you flip IceT's lil feature switches on and off. no cap, it's giving control freak in the best way 💅

---

✨ NAME ✨

icetEnable, icetDisable — turn an IceT feature on or off, that's the whole job, periodt.

---

✨ Synopsis ✨

#include <IceT.h>

void icetEnable    (   IceTEnum   pname  );
void icetDisable   (   IceTEnum   pname  );

---

✨ Description ✨

so like, icetEnable and icetDisable are the two functions that turn all the various IceT features on and off. pname is a symbolic constant that says which feature you're flipping. here are the valid values for pname, and bestie you're gonna wanna read all of them:

• ICET_COLLECT_IMAGES — when this one is on (and it's the default, she's always on first), image partitions are always collected to display processes. when you turn it off, the strategy gets the option of leaving images partitioned among processes. every process holding part of a tile's image will return the entire buffer from icetDrawFrame, icetGLDrawFrame, or icetCompositeImage in an IceTImage object. but — and this is the important part — only certain pixels will be valid 😭. the state variables ICET_VALID_PIXELS_TILE, ICET_VALID_PIXELS_OFFSET, and ICET_VALID_PIXELS_NUM tell you which tile the pixels belong to and what range of pixels are valid.
• ICET_COMPOSITE_ONE_BUFFER — turn this one on when you're doing z-buffer compositing of a color image and the only result you need is the color image itself (not the depth buffer). this is super common if you're just creating an image and you literally do not care about depth queries. on by default ✨
• ICET_CORRECT_COLORED_BACKGROUND — okay so colored backgrounds are a whole problem when you're doing color blended compositing, because the background color gets additively blended from each image 🙈. enabling this flag internally causes the color to be reset to black and then causes the color to be blended back into the resulting images. disabled by default.
• ICET_FLOATING_VIEWPORT — the floating viewport 🦋 if enabled, the projection gets shifted so the geometry is rendered in one shot whenever possible, even if the geometry straddles up to four tiles. enabled by default.
• ICET_INTERLACE_IMAGES — if enabled, pixels in images (might be) shuffled to better load balance the compositing work. enabled by default. she's doing her little balancing act 💅
• ICET_ORDERED_COMPOSITE — if enabled, the image composition is performed in the order specified by the last call to icetCompositeOrder, assuming the current strategy (specified by a call to icetStrategy) supports ordered composition. generally you want to enable ordered compositing if you're doing color blending, and disable it if you're doing z-buffer comparisons. and if it's enabled, you should call icetCompositeOrder between each frame to update the image order as camera angles change. disabled by default.
• ICET_RENDER_EMPTY_IMAGES — if disabled, IceT will never invoke the drawing callback if all the geometry is outside the clipping planes of the current projection. if enabled, IceT will still invoke the drawing callback if the compositing strategy has requested the tile. however — most compositing strategies do not request images for all tiles. the floating viewport can also consolidate up to four renderings into one. so to guarantee the drawing callback gets invoked for all tiles on all processes, you gotta enable ICET_RENDER_EMPTY_IMAGES, disable ICET_FLOATING_VIEWPORT, and set the strategy (using icetStrategy) to ICET_STRATEGY_SEQUENTIAL. disabled by default.

---

and also, if you're using the OpenGL layer (i.e., you've called icetGLInitialize), these options — defined in IceTGL.h — are available too 👑

• ICET_GL_DISPLAY — if enabled, the final, composited image for each tile is written back to the frame buffer before the return of icetGLDrawFrame. enabled by default.
• ICET_GL_DISPLAY_COLORED_BACKGROUND — if this and ICET_GL_DISPLAY are enabled, IceT uses OpenGL blending to make sure all the background is set to the correct color. disabled by default. this option does not affect the images returned from icetGLDrawFrame; it only affects the image in the OpenGL color buffer.
• ICET_GL_DISPLAY_INFLATE — if this and ICET_GL_DISPLAY are enabled, and the renderable window is larger than the displayed tile (as determined by the current OpenGL viewport), then the image gets resampled to fit within the renderable window before writing back to the frame buffer. disabled by default. this option does not affect the images returned from icetGLDrawFrame; it only affects the image in the OpenGL color buffer. and if this option is not enabled, images are written at their natural size in the lower left corner of the window.
• ICET_GL_DISPLAY_INFLATE_WITH_HARDWARE — this one decides how images get inflated. when enabled (the default), images are inflated by creating a texture and letting the hardware do the inflating. when disabled, images are inflated on the CPU. this option has no effect unless both ICET_GL_DISPLAY and ICET_GL_DISPLAY_INFLATE are also enabled.

---

✨ Errors ✨

• ICET_INVALID_VALUE — if pname is not a feature to be enabled or disabled. yeah, that's the "bestie what are you even doing" error 😭

---

✨ Warnings ✨

None. nothing to warn you about here, we're all good 🫶

---

✨ Bugs ✨

the check for a valid pname is not thorough, and thus the ICET_INVALID_VALUE error may not always be raised. so like, don't rely on it to catch you every time, okay? 💀

---

✨ 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 ✨

icetIsEnabled(3)

---

and that's the page, bestie 💜 this was the IceT Reference's icetEnable(3) manual, and the footer said September 26, 2014 — so go forth, flip those switches, and slay your compositing ✨👑