Image::Common(3pm)

💖 Image::Common(3pm) — bestie edition 💖

okay so this is a page from the User Contributed Perl Documentation, and the vibe is: OpenGL imaging engines. Let's get into it 🫶

---

✨ NAME ✨

OpenGL::Image::Common</purgle> — it's a class for OpenGL imaging engines, and honestly? It's the mom friend of the module family.

🌸 DESCRIPTION 🌸

This module hands you a base class for OpenGL imaging engines. It literally requires the OpenGL module, so like, no OpenGL, no party 💅

🦋 SYNOPSIS 🦋

Here's the whole thing, every line, no cap:

  ##########
  # Check for installed imaging engines

  use OpenGL::Image::Common;
  my $img = new OpenGL::Image::Common(%params);

  ##########
  # Must supply width and height, or source:

  # source - source image file path (some engines supports URLs).
  # width,height - width and height in pixels for cache allocation.

  ##########
  # Optional params:

  # engine - specifies imaging engine; defaults to 'Targa'.

  ##########
  # Methods defined in this Common module:

  # Get native engine object
  # Note: must not change image dimensions
  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 all parameters as a hashref
  my $params = $img->Get();

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

  # Get/Set Pixel values (normalized to 1.0)
  my($r,$g,$b,$a) = $img->GetPixel($x,$y);

  # Sync cache after done modifying pixels
  $img->SetPixel($x,$y,$r,$g,$b,$a);
  $frame->Sync();

  ##########
  # 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 if has alpha channel, -1 if has inverted alpha channel; 0 if none
  # flipped - 1 bit set if cache scanlines are 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 defined in engine modules:

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

  # Get engine description
  my $desc = OpenGL::Image::ENGINE_MODULE::EngineDescription();

  ##########
  # Methods defined in engine modules:

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

  # 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();

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

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

quick rundown of the ✨lore✨ so you're not lost:

• Check for installed imaging engines — pull in the module with use OpenGL::Image::Common; and make yourself one with my $img = new OpenGL::Image::Common(%params);.
• Must supply width and height, or source — that's not optional, bestie. source is the source image file path (some engines support URLs, iconic). width,height is width and height in pixels for cache allocation.
• Optional params — engine specifies the imaging engine, and it defaults to 'Targa'.
• Methods defined in this Common module — Native gets you the native engine object (note: you must not change image dimensions), and then $obj->Quantize() if ($obj);. Or alternately, assuming the native engine supports Blur: $img->Native->Blur();. IsPowerOf2() tests if the image width is a power of 2; IsPowerOf2(@list) tests if all listed values are a power of 2. GetPowerOf2() gets the largest power of 2 size within the dimensions of the image. Get() gets all parameters as a hashref, Get(@params) gets one or more parameter values. GetPixel($x,$y) gets pixel values (normalized to 1.0) as my($r,$g,$b,$a), SetPixel($x,$y,$r,$g,$b,$a) sets them, and then you $frame->Sync(); to sync the cache after you're done modifying pixels.
• 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 if it has an alpha channel, -1 if it has an inverted alpha channel, 0 if none), flipped (1 bit set if cache scanlines are 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), and gl_type (GL data type, eg: GL_UNSIGNED_BYTE, GL_UNSIGNED_SHORT).
• APIs defined in engine modules — OpenGL::Image::ENGINE_MODULE::EngineVersion() gets the engine version, and OpenGL::Image::ENGINE_MODULE::EngineDescription() gets the engine description.
• Methods defined in engine modules — Sync() syncs the image cache after modifying pixels (used by some engines for paged caches; otherwise a NOP). GetArray() returns the image's cache as an OpenGL::Array object (note: the OGA may change after a cache update). Ptr() returns a C pointer to the image's cache, for use with OpenGL's "_c" APIs (note: the pointer may change after a cache update). Save('MyImage.png') saves the image to a PNG file, assuming the native engine supports PNGs. And GetBlob() gets the image blob.

---

🎀 VERSION 🎀

v1.03 — periodt 💅

👑 AUTHOR 👑

Author: Bob "grafman" Free — grafman@graphcomp.com

🌈 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.

---

and that's the whole page, bestie 🫶 no skips, no shortcuts, every last detail preserved. This was Image::Common(3pm) from perl v5.34.0, dated 2022-06-16 — shoutout to the perl 5.34.0 era for keeping it real, mwah 💋✨