icetImageCopyColor(3)

💖 NAME 💖

icetImageCopyColor, icetImageCopyDepth — bestie, these are the ones that retrieve pixel data from an image. fr fr.

---

✨ Synopsis ✨

Okay so first things first, you gotta pull in the header:

#include <IceT.h>

Then here's the whole squad, verbatim, no cap:

void   icetImageCopyColorub(   const IceTImage   image,
                               IceTUByte *       color_buffer,
                               IceTEnum          color_format  );

void   icetImageCopyColorf(   const IceTImage   image,
                              IceTFloat *       color_buffer,
                              IceTEnum          color_format  );

void   icetImageCopyDepthf(   const IceTImage   image,
                              IceTFloat *       depth_buffer,
                              IceTEnum          depth_format  );

---

🎀 Description 🎀

So the icetImageCopyColor suite of functions is the one that pulls color data out of images, and the icetImageCopyDepth functions pull depth data out of images. Two little families, one job: get the pixels outta there. 💅

Every one of these takes a pointer to a buffer that you already made, and that buffer has to be big enough to hold all the pixels in the image. The data gets copied into those buffers, and format conversions happen along the way as necessary. 🌈

And here's the part that actually matters, bestie — because the data is copied into the buffer you hand over, messing with the values in that buffer afterwards does not touch the image object at all. That's the opposite of how icetImageGetColor and icetImageGetDepth behave, iykyk. 👀

The pixel data is always tightly packed in horizontal major order. For color data made of tuples like RGBA, the components for each pixel are packed together in that order. The very first entry in the array is the pixel in the lower left corner of the image. The next entry is immediately to the right of that first pixel, and so on down the line. 🦋

Wanna know how big the array is? Get the dimensions with the icetImageGetWidth and icetImageGetHeight functions. Easy.

Each of these functions gives you a typed version of the image data array. They can only succeed if the type you're requesting matches the type specified by the color_format or depth_format argument. Like, it is genuinely an error to request unsigned byte color data for a floating point color format. 😭 And yeah, specifying the format might feel redundant (couldn't you just infer it from the type being retrieved?), but IceT requires it anyway — for completeness, and to support possible future data formats. Slay, forward thinking. ✨

• Use icetImageCopyColorub to retrieve an array of 8-bit unsigned bytes. Using this function is only valid if color_format is ICET_IMAGE_COLOR_RGBA_UBYTE.
• Use icetImageCopyColorf to retrieve an array of floating point color values. Using this function is only valid if color_format is ICET_IMAGE_COLOR_RGBA_FLOAT or ICET_IMAGE_COLOR_RGB_FLOAT.
• Use icetImageGetDepthf to retrieve an array of floating point depth values. Using this function is only valid if depth_format is ICET_IMAGE_DEPTH_FLOAT.

---

💀 Errors 💀

• ICET_INVALID_OPERATION — the image object does not have a color or depth buffer from which to copy data. It's giving nothing to copy. 🙈
• ICET_INVALID_ENUM — the color_format or depth_format you requested is incompatible with the type of the buffer. Mismatch era, not the cute kind. 💔

---

🫶 Warnings 🫶

None. Zero. Nada. We're safe out here. ✨

---

🌸 Bugs 🌸

None known. Iconic behavior, honestly. 👑

---

⭐ 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 👑

• icetImageGetColor(3)
• icetImageGetDepth(3)

---

Okay that's the whole page, bestie — this is the IceT Reference, dated March 13, 2018, and it's the icetImageCopyColor(3) manual. Go forth and copy those pixels. 🎀✨🦋