afterimage(3x)

💖 NAME 💖

okay bestie so this is afterimage — it's the big-picture overview page for the libAfterImage image library. It also answers to libAfterImage/libAfterImage. And like, what even is it? It's a generic imaging library that was originally designed for the AfterStep X Window Manager. That's the whole vibe. ✨

---

🎯 PURPOSE 🎯

libAfterImage is the imaging library that got built for the AfterStep X Window Manager — but it got generalized so literally any app that needs a robust graphics engine can use it too. Sharing is caring fr fr. 🫶

Here's the tea on what it gives you:

• loading images from files of different formats
• compressed in-memory storage of images
• scaling
• tinting / shading
• flipping
• superimposition of an arbitrary number of images over each other
• drawing linear gradients
• antialiased / smoothed text drawing using both the FreeType library and X Window fonts

The primary goals of this library are to get exceptional quality out of images and text while also making the code fast and small at the same time. Iconic multitasking. 💅

Extra steps get taken to compensate for screen colordepth limitations, and different error diffusion algorithms are used so images stay smooth even in low colordepth modes. No crunchy pixels here. 🦋

---

📜 HISTORY 📜

ngl the whole reason libAfterImage exists is that it was implemented as an attempt to address several issues.

Issue one, and the most important one: the X Window System completely lacks any tools for image manipulation, except for very rudimentary operations. With the introduction of Render extensions in XFree86 4.0, that situation is changing, but it's still far from perfect. So there's a need to implement client side image manipulation. Which then creates a problem of image data transfer between Server and client. 😭

To avoid that, you need full-time image storage on the client side. Which is memory extensive. So now there's a need for some in-memory compression. It's a whole chain of problems, iykyk.

On the other side there's the image quality issue. It's easy to write a scaling function by simply dropping out or duplicating pixels, but the quality is awful. What you actually need is very fast averaging / interpolation code. Which brings us to the issue of 8 bits per channel: add two pixels together and you get overflow. So all the math has to be performed in a different colorspace and then converted back. But on the other side, that conversion may discard valuable bits, so some compensation method has to be implemented. The audacity of bits. 💀

On the text drawing side of things, there are numerous problems just as well. Native X fonts look ugly as soon as you try to show any decently sized text. That's supposed to be solved by those aforementioned Render extensions to XFree86, but as experience has shown, things aren't as easy as they look — besides, you want your app to run well under any X Server. The FreeType library provides a solution, but it's not always available. Another problem: if you keep all your images on the client side, you want to draw text on the client side as well.

The solution is to provide a transparent interface that could use both X fonts and FreeType, cache glyphs on the client side, and possibly perform smoothing of ugly X fonts.

There is no library solving all these problems in one fell swoop, except for monstrous ones, like ImLib. 🙈

Hence libAfterImage has come to life. ✨👑

---

🌈 DESCRIPTION 🌈

libAfterStep provides several facilities. Let's go through them one by one bestie:

1. X Visual abstraction layer via ASVisual. This layer handles color management, transfer of data to and from X Server, and other screen related stuff.
2. Scanline handling facility via ASScanline. ASScanline is the most widely used structure since image handling is implemented on a per-scanline basis.
3. Image storage, transformation and rendering via ASImage. ASImage provides a generic container used for any image or text manipulation. It incorporates such robust facilities as in-memory RLE compression, and separate channel storage of 4 channels ( Alpha, Red, Green, and Blue ) with 8 bit per channel. Slay.
4. Simplified font handling facility via ASFont and ASFointManager. All the font handling is done using the ASFont structure, no matter what type of font is used. Any font supported by X11 and FreeType can be used. 🤝
5. Transparent image file reading for many different formats. It includes built-in XPM reading code and XCF ( GIMP's native format ). Overall supported:
   • via external libraries : XPM, JPEG, PNG, TIFF, GIF
   • via built in code : XPM, XCF, PNM, PPM, BMP, ICO, CUR

Note that XPM can be supported both via built-in code or via libXpm, depending on compilation configuration. Actual image file format is autodetected from the file contents — the file name extension is not used and can be anything at all. Sneaky but make it fashion. 💅

6. Image export into many popular file formats. Currently implemented : XPM, JPEG, PNG, GIF. Work is underway to implement support for TIFF, XCF, BMP, ICO.
7. Image quantization to arbitrary size colormap.
8. libAfterImage could be used without X window system, which is convenient for such things as web development. An XML Image manipulation tool that could be used in such activity is included ( see ascompose.c ). 👑
9. Image reference counting.

---

🧩 USES 🧩

libAfterBase — the AfterStep basic functionality library. That includes hash tables, file search methods, message output, and generic types.

However, effort has been made to allow for standalone configuration as well. If libAfterBase is not found at compilation time, libAfterImage will use the extract from libAfterBase included with libAfterImage. Self-sufficient queen fr fr. 💜

---

👀 SEE ALSO 👀

• Examples
• API Reference

---

📝 TODO 📝

• Implement support for Targa and PCX image format and maybe some other formats as well.
• Implement complete support for I18N internationalization.
• Implement color<->pixel conversion for all colordepths.

(the to-do list is giving "I'll do it tomorrow" energy and honestly, same 🫶)

---

🎀 AUTHOR 🎀

Sasha Vasko <sasha at aftercode dot net>

libAfterImage/Examples

---

🖼️ EXAMPLE 🖼️

• ASView — image loading from the file and displaying in window.
• ASScale — image loading from file and scaling to arbitrary size.
• ASTile — image loading from file, tiling and tinting to arbitrary size and color.
• ASMerge — image loading and merging with another image.
• ASGrad — multipoint gradient drawing.
• ASFlip — image loading from file and rotation.
• ASText — texturized semitransparent antialiased text drawing.

---

🔎 SEE ALSO (the sequel) 🔎

• API Reference
• libAfterImage/API Reference

---

👶 CHILDREN 👶

Headers :

ascmap.h asfont.h asimage.h asvisual.h blender.h export.h
import.h transform.h ximage.h

Structures :

• ColorPair
• ASScanline
• ASVisual
• ASImage
• ASImageManager
• ASImageBevel
• ASImageDecoder
• ASImageOutput
• ASImageLayer
• ASGradient
• ASFontManager
• ASFont
• ASGlyph
• ASGlyphRange
• ASColormap
• ASImageExportParams
• ASVectorPalette

Functions :

ASScanline handling:

• prepare_scanline(), free_scanline()

ASVisual initialization :

• query_screen_visual(), setup_truecolor_visual(), setup_pseudo_visual(), setup_as_colormap(), create_asvisual(), create_asvisual_for_id(), destroy_asvisual()

ASVisual encoding/decoding :

• visual2visual_prop(), visual_prop2visual()

ASVisual convenience functions :

• create_visual_window(), create_visual_pixmap(), create_visual_ximage(), create_visual_gc()

Colorspace conversion :

• rgb2value(), rgb2saturation(), rgb2hue(), rgb2luminance(), rgb2hsv(), rgb2hls(), hsv2rgb(), hls2rgb(), degrees2hue16(), hue162degrees(), normalize_degrees_val()

Image quantization :

• colormap_asimage(), destroy_colormap()

merge_scanline methods :

• alphablend_scanlines(), allanon_scanlines(), tint_scanlines(), add_scanlines(), sub_scanlines(), diff_scanlines(), darken_scanlines(), lighten_scanlines(), screen_scanlines(), overlay_scanlines(), hue_scanlines(), saturate_scanlines(), value_scanlines(), colorize_scanlines(), dissipate_scanlines().

ASImage handling :

• asimage_init(), asimage_start(), create_asimage(), clone_asimage(), destroy_asimage()

ASImage channel data manipulations :

• get_asimage_chanmask(), move_asimage_channel(), copy_asimage_channel(), copy_asimage_lines()

ImageManager Reference counting and managing :

• create_image_manager(), destroy_image_manager(), store_asimage(), fetch_asimage(), dup_asimage(), release_asimage(), release_asimage_by_name()

Layers helper functions :

• init_image_layers(), create_image_layers(), destroy_image_layers()

Encoding :

• asimage_add_line(), asimage_add_line_mono(), asimage_print_line()

Decoding :

• start_image_decoding(), stop_image_decoding(), asimage_decode_line (), set_decoder_shift(), set_decoder_bevel_geom(), set_decoder_back_color()

ASImage from scientific data :

• set_asimage_vector(), colorize_asimage_vector(), create_asimage_from_vector()

Output :

• start_image_output(), set_image_output_back_color(), toggle_image_output_direction(), stop_image_output()

X11 conversions :

• ximage2asimage(), pixmap2asimage(), asimage2ximage(), asimage2mask_ximage(), asimage2pixmap(), asimage2mask()

Transformations :

• scale_asimage(), tile_asimage(), merge_layers(), make_gradient(), flip_asimage(), mirror_asimage(), pad_asimage(), blur_asimage_gauss(), fill_asimage(), adjust_asimage_hsv()

Import :

• file2ASImage(), file2pixmap()

Export :

• ASImage2file()

Text Drawing :

• create_font_manager(), destroy_font_manager(), open_freetype_font(), open_X11_font(), get_asfont(), release_font(), print_asfont(), print_asglyph(), draw_text(), draw_fancy_text()

---

and that's the whole page bestie!! 🎀 this absolute icon of a document came to you from the 3rd Berkeley Distribution, AfterStep v.2.2.12, and the afterimage(3x) page itself. go forth and manipulate some images, you main character. 💖✨🦋💅