icetImageGetColor(3)

💖 icetImageGetColor(3) — IceT Reference ✨

okay bestie, gather round, because today we're talking about icetImageGetColor and its little sibling icetImageGetDepth — the duo that pulls pixel data straight out of an image 💅. This is from the IceT Reference, and it's lowkey one of the most useful things you'll ever touch, fr fr.

---

🌸 NAME 🌸

icetImageGetColor, icetImageGetDepth — retrieve pixel data buffer from image 🎀

---

🦋 Synopsis 🦋

#include <IceT.h>

IceTUByte *   icetImageGetColorub   (  IceTImage   image  );
IceTUInt *    icetImageGetColorui   (  IceTImage   image  );
IceTFloat *   icetImageGetColorf    (  IceTImage   image  );
IceTFloat *   icetImageGetDepthf    (  IceTImage   image  );

const IceTUByte *   icetImageGetColorcub   (
  const IceTImage   image  );
const IceTUInt *    icetImageGetColorcui   (
  const IceTImage   image  );
const IceTFloat *   icetImageGetColorcf    (
  const IceTImage   image  );
const IceTFloat *   icetImageGetDepthcf    (
  const IceTImage   image  );

---

✨ Description ✨

So the icetImageGetColor suite of functions goes and gets you the color data from an image, and the icetImageGetDepth functions get you the depth data. Each one hands you back a pointer to a buffer that lives inside the image, no cap. 🫶

Heads up bestie: writing to that data changes the data within the image object itself. It's not a copy, it's the real thing. 💀

You're supposed to use icetImageGetColor and icetImageGetDepth from inside drawing callbacks to pass image data back to IceT. That's the vibe. ✨

The pixel data is always tightly packed in horizontal major order. Color data that's made of tuples — like RGBA — has the components for each pixel packed together in that order. The first entry in the array corresponds to the pixel in the lower left corner of the image. The next entry is immediately to the right of the first pixel, and so on and so on. 🌈

Wanna know the dimensions of that array? Use the icetImageGetWidth and icetImageGetHeight functions, queen. 👑

Each of these functions returns a typed version of the image data array, and they can only succeed if the type you're requesting matches the internal type of the array. Like, it is an error to request unsigned byte color data when the image stores images as floating point colors. Not me asking for the wrong type 😭.

You can use icetImageGetColorFormat and icetImageGetDepthFormat to retrieve the format for the internal data storage (which also implies the base data type). You can also use icetImageCopyColor and icetImageCopyDepth to convert the image data to whatever format you like. Options, options, iconic. 💅

Now let's break down each one, shall we:

• icetImageGetColorub — use this to retrieve an array of 8-bit unsigned bytes. Only valid if the color format is ICET_IMAGE_COLOR_RGBA_UBYTE.
• icetImageGetColorui — use this to retrieve an array of 32-bit unsigned integers. Only valid if the color format is ICET_IMAGE_COLOR_RGBA_UBYTE. In this case, each 32-bit integer represents all four RGBA channels. Accessing each pixel's color values as a single 32-bit integer is often faster than accessing it as 4 independent 8-bit integers, because most modern architectures can access 32-bit memory boundaries faster than independent 8-bit boundaries. Slay, architecture. 🔥
• icetImageGetColorf — use this to retrieve an array of floating point color values. Only valid if the color format is ICET_IMAGE_COLOR_RGBA_FLOAT or ICET_IMAGE_COLOR_RGB_FLOAT.
• icetImageGetDepthf — use this to retrieve an array of floating point depth values. Only valid if the depth format is ICET_IMAGE_DEPTH_FLOAT.

---

🎀 Return Value 🎀

Returns an appropriately typed array pointing to the internal color or depth values stored in the image object. If there's an error, NULL is returned. 🙈

The memory returned should not be freed. It's managed internally by IceT. Hands off, bestie. 🫶

---

💀 Errors 💀

• ICET_INVALID_OPERATION — the internal color or depth format is incompatible with the type of array the function retrieves. It's giving mismatch, and not the cute kind. 😭

---

🌟 Warnings 🌟

None. We're safe, we're unbothered, we're thriving. ✨

---

🧚 Bugs 🧚

None known. Periodt. 💅

---

💜 Notes 💜

Okay so here's the tea: there is no mechanism to automatically determine the data type from the color or depth format enumeration (the one you get back from icetImageGetColorFormat or icetImageGetDepthFormat). Instead, you have to code your own internal logic to use an array of the appropriate type. 😤

Why, you ask? The reasoning behind this decision is that the format encodes the data layout in addition to the data type, and your code must understand the basic semantics of the data to do anything worthwhile with it. If you want to write code that's indifferent to the underlying format of the image, use the icetImageCopyColor and icetImageCopyDepth functions to copy the data to a known format. iykyk 🌈

---

👑 Copyright 👑

Copyright (C)2010 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 🌈

icetImageCopyColor(3), icetImageCopyDepth(3), icetImageGetColorFormat(3), icetImageGetDepthFormat(3)

---

and that's the whole page, bestie — no cap, every last detail preserved 🫶💖 this was the IceT Reference, dated March 13, 2018. go forth and get those pixels, you absolute icon ✨👑🎀