Image(3pm)

🌸 Image(3pm) — OpenGL::Image 💅

okay so bestie, you opened Image(3pm) and I'm here to tell you it's the OpenGL::Image page and it's lowkey iconic. grab a strawberry drink 🍓, sit criss-cross, we're doing this. 🎀

---

✨ NAME ✨

OpenGL::Image — an OpenGL wrapper to load images 🖼️✨

---

💖 DESCRIPTION 💖

So basically: this module is an extensible wrapper to abstract imaging interfaces. Translation? It's the friend who stands between you and whatever imaging library you're feeling that day, so you never have to commit. main character energy fr fr. 💅

By default, it rolls with the OpenGL::Image::Targa module. Wanna invite other imaging libraries to the function? Say less — support for them may be added by providing plug-in modules in the OpenGL/Image folder. 🦋

There's also an OpenGL::Image::Magick module provided for use with PerlMagick. And ngl, for best performance you want ImageMagick 6.3.5 or newer installed. periodt. 👑

---

🌈 SYNOPSIS 🌈

here's the whole vibe, copied with love and precision. every comment, every call, every _c suffix stays exactly where it is. 💜

  ##########
  # Check for installed imaging engines
  use OpenGL::Image;

  # Get hashref of installed imaging engines
  # Keys are engine names; values are info hashes, including version,
  # priority (1 .. n, 1 is highest), module (Perl module name)
  # and description.
  # Priority can be set using Engines.lst (see INSTALL); otherwise
  # 'Targa' has top priority, and others are in unspecified order.
  my $engine_hashref = OpenGL::Image::GetEngines();

  # In list context, returns list of info hashes sorted by engine
  # priority; info hash does not include a priority value.
  my @sorted_engine_info = OpenGL::Image::GetEngines();

  # Check for a specific engine and optional version support
  # Returns an info hashref for the engine if available; otherwise undef.
  my $info_hashref = OpenGL::Image::HasEngine('Magick','6.3.5');

  ##########
  # Load texture - defaults to highest priority engine if none specified;
  # if Engines.lst is not specified, the highest priority is the Targa engine.
  my $tex = new OpenGL::Image(source=>'test.tga');

  # Get GL info
  my($ifmt,$fmt,$type) = $tex->Get('gl_internalformat','gl_format','gl_type');
  my($w,$h) = $tex->Get('width','height');

  # Test if power of 2
  if (!$tex->IsPowerOf2()) return;

  # Set texture
  glTexImage2D_c(GL_TEXTURE_2D, 0, $ifmt, $w, $h, 0, $fmt, $type, $tex->Ptr());

  ##########
  # Modify GL frame using ImageMagick
  my $frame = new OpenGL::Image(engine=>'Magick',width=>$w,height=>$h);

  # Get default GL info
  my($def_fmt,$def_type) = $tex->Get('gl_format','gl_type');

  # Read frame pixels
  glReadPixels_c(0, 0, $width, $height, $def_fmt, $def_type, $frame->Ptr());

  # Sync native image buffer
  # Must use this prior to making native calls
  $frame->Sync();

  # Modify frame pixels
  $frame->Native->Blur();

  # Sync OGA
  # Must use this atfer all native calls are done
  $frame->SyncOGA();

  # Draw back to frame
  glDrawPixels_c(0, 0, $width, $height, $def_fmt, $def_type, $frame->Ptr());

  ##########
  # Save GL frame
  my $image = new OpenGL::Image(width=>$width,height=>$height);

  # Read frame pixels
  glReadPixels_c(0, 0, $width, $height, $def_fmt, $def_type, $image->Ptr());

  # Save file - automatically does a Sync before write
  $image->Save('MyImage.tga');

  ##########
  # Get/Set normalized pixels

  my($r,$g,$b,$a) = $img->GetPixel($x,$y);

  $img->SetPixel($x,$y, 1.0, 0.5, 0.0, 1.0);

  # Sync cache after done modifying pixels
  $frame->Sync();

  ##########
  # Methods defined in OpenGL::Image::Common:

  # Get native engine object
  my $obj = $img->Native;
  $obj->Quantize() if ($obj);

  # Alternately (Assuming the native engine supports Blur):
  $img->Native->Blur();

  # Test if image width is a power of 2
  if ($img->IsPowerOf2());

  # Test if all listed values are a power of 2
  if ($img->IsPowerOf2(@list));

  # Get largest power of 2 size within dimensions of image
  my $size = $img->GetPowerOf2();

  # Get one or more parameter values
  my @values = $img->Get(@params);

  # Return the image's cache as an OpenGL::Array object.
  # Note: OGA may change after a cache update
  my $oga = $img->GetArray();

  # Return a C pointer to the image's cache.
  # For use with OpenGL's "_c" APIs.
  # Note: pointer may change after a cache update
  $img->Ptr();

  ##########
  # Supported parameters:

  # version - version of the engine
  # source - source image, if defined
  # width - width of image in pixels
  # height - height of image in pixels
  # pixels - number of pixels
  # components - number of pixel components
  # size - bytes per component
  # length - cache size in bytes
  # endian - 1 if big endian; otherwise 0
  # alpha - 1: normal alpha channel, -1: inverted alpha channel; 0: none
  # flipped - 1 bit set if cache ordered top to bottom; others reserved
  # gl_internalformat - internal GL pixel format. eg: GL_RGBA8, GL_RGBA16
  # gl_format - GL pixel format. eg: GL_RGBA, GL_BGRA
  # gl_type - GL data type.  eg: GL_UNSIGNED_BYTE, GL_UNSIGNED_SHORT

  ##########
  # APIs and Methods defined in engine modules:

  # Get engine version
  my $ver = OpenGL::Image::ENGINE_MODULE::EngineVersion();

  # Sync the image cache after a write.
  # Used by some engines for paged caches; otherwise a NOP.
  $img->Sync();

  # Save the image to a PNG file (assuming the engine supports PNGs)
  $img->Save('MyImage.png');

  # Get image blob.
  my $blob = $img->GetBlob();

a couple things worth calling out before you run off, bestie 👇

• GetEngines() gives you a hashref of installed imaging engines in scalar context — keys are engine names, values are info hashes carrying version, priority (1 .. n, where 1 is highest), module (the Perl module name) and description. Priority can be set using Engines.lst (peep INSTALL); otherwise 'Targa' has top priority and the others are in unspecified order. 🙈
• In list context, GetEngines() hands back a list of info hashes sorted by engine priority — and heads up, that info hash does not include a priority value. 🤓
• HasEngine('Magick','6.3.5') checks for a specific engine plus optional version support. It returns an info hashref if the engine is available, and undef otherwise. no notes. 💅
• Loading a texture with new OpenGL::Image(source=>'test.tga') defaults to the highest priority engine if you don't name one — and if Engines.lst isn't specified, that highest priority is the Targa engine. 🎀
• When you're doing native calls, the order is sacred: $frame->Sync() must be used prior to making native calls, and $frame->SyncOGA() must be used after all native calls are done. don't skip it, it's giving chaos if you do. 😭
• $image->Save('MyImage.tga') automatically does a Sync before write. obsessed. ✨
• $img->GetArray() returns the image's cache as an OpenGL::Array object, and $img->Ptr() returns a C pointer to the image's cache for use with OpenGL's "_c" APIs — but note: the OGA may change after a cache update, and the pointer may change after a cache update. so don't be holding onto stale ones. 💀
• $img->Sync() syncs the image cache after a write; some engines use it for paged caches, otherwise it's a NOP. and $img->Save('MyImage.png') saves to PNG assuming the engine supports PNGs. 🦋

---

⭐ VERSION ⭐

v1.03 — yeah she's been around, she's refined. 💜

---

👑 AUTHOR 👑

• Author: Bob "grafman" Free — grafman@graphcomp.com
• Contributor: Geoff Broadwell

shoutout to the devs, we love a collaborative moment. 🫶

---

💖 COPYRIGHT AND LICENSE 💖

copyright 2007 Graphcomp - ALL RIGHTS RESERVED

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

the license is literally the same terms as Perl itself, so go be free and modify responsibly bestie, just keep those terms intact. 🎀

---

okay that's the whole page, and fr fr you now know it better than the person who wrote it (no shade). mwah 💋 this was documented by perl v5.34.0 on 2022-06-16, so yeah, that's the lore. slay, go load some textures. 🌸✨🦋