import(3x)

🌸 NAME 🌸

okay bestie, gather round 💖 this is import(3x) — the glow-up page for the AfterStep X11 window manager's import situation. Real talk:

• import — functionality for reading images from files
• and it lives in libAfterImage/import.h 📂

---

✨ NAMEimport ✨

import is literally the icon of image file format autodetection, plus all the reading and decoding routines that go with it. no cap 💅

---

🦋 SEE ALSO 🦋

Functions (the besties it runs with):

• file2ASImage()
• get_asimage()
• file2pixmap()

Other libAfterImage modules (the whole friend group 🫶):

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

---

👑 AUTHOR 👑

Sasha Vasko — <sasha at aftercode dot net> 💖 absolute legend, main character energy fr fr.

Also tagging along in this section: libAfterImage/gamma 🎀

---

🌈 NAMESCREEN_GAMMA 🌈

defines the default value for screen gamma correction. that's it, that's the whole vibe ✨

💫 SOURCE 💫

#define SCREEN_GAMMA 2.2 #define DEFAULT_PNG_IMAGE_GAMMA     0.45455

---

🎀 libAfterImage/ASImageFileTypes 🎀

✨ NAMEASImageFileTypes ✨

it's the list of known image file formats. like the guest list but for file types 💅

💫 SOURCE 💫

typedef enum {
    ASIT_Xpm = 0,
    ASIT_ZCompressedXpm,
    ASIT_GZCompressedXpm,
    ASIT_Png,
    ASIT_Jpeg,
    ASIT_Xcf,
    ASIT_Ppm,
    ASIT_Pnm,
    ASIT_Bmp,
    ASIT_Ico,
    ASIT_Cur,
    ASIT_Gif,
    ASIT_Tiff,
    ASIT_XMLScript,
    ASIT_SVG,
    /* reserved for future implementation : */
    ASIT_Xbm,
    ASIT_Targa,
    ASIT_Supported = ASIT_Targa,
    ASIT_Pcx,
    ASIT_HTML,
    ASIT_XML,
    ASIT_Unknown }ASImageFileTypes;

---

🧚 libAfterImage/ASImageListEntry 🧚

✨ NAMEASImageListEntry ✨

one entry in a linked list of images loaded from a single directory 🍓 (bestie, it's a whole linked list — prev and next and everything, so dramatic).

💫 SOURCE 💫

typedef struct ASImageListEntryBuffer {
#define ASILEB_Dirty       (0x01<<0)
#define ASILEB_Binary      (0x01<<1)

    ASFlagType flags ;

    size_t size ;
    char  *data ;

}ASImageListEntryBuffer;

typedef struct ASImageListEntry {
#define MAGIC_ASIMAGE_LIST_ENTRY 0xA3A311E4
#define IS_ASIMAGE_LIST_ENTRY(e)  (((e)!=NULL)&&((e)->magic==MAGIC_ASIMAGE_LIST_ENTRY)&&((e)->ref_count>0))

    unsigned long magic ;
    struct ASImageListEntry *prev, *next ;
    char   *name ;
    char   *fullfilename ;

    ASImageFileTypes    type;
    ASImage            *preview;

#ifndef _WIN32
    mode_t d_mode;
#endif
    time_t d_mtime;
    off_t  d_size;      /* total size, in bytes */

    ASImageListEntryBuffer *buffer ;

    int ref_count;
}ASImageListEntry;

---

💖 libAfterImage/import/file2ASImage() 💖

🌸 NAMEfile2ASImage() 🌸

load an ASImage from a file. yes it's giving exactly what it says on the tin ✨

💫 SYNOPSIS 💫

ASImage *file2ASImage( const char *file, ASFlagType what,
                       double gamma,
                       unsigned int compression, ... );

🎀 INPUTS 🎀

• file — file name, with or without a directory name
• what — reserved for future use (so, placeholder core, don't come for her 💀)
• gamma — the gamma value used to correct the image
• compression — the compression level of the resulting ASImage
• ... — a NULL-terminated list of strings, representing an arbitrary number of directories to be searched. each one. yes, each. 🙈

⭐ RETURN VALUE ⭐

A pointer to the ASImage structure holding the image data on success. NULL on failure, bestie 😭

🦋 DESCRIPTION 🦋

so file2ASImage is gonna try to interpret that filename in the following ways, in order:

1. It will try to find the file using the unmodified filename in all the provided search paths.
2. It will attempt to append .gz and then .Z to the filename and find such a file in all the provided search paths.
3. If the filename ends with an extension consisting of digits only, it will attempt to find the file with this extension stripped off. On success, this extension will be used to load a subimage from the file with that number. Heads up: subimages are supported only for XCF, GIF, BMP, ICO and CUR files — that's the whole list, no extras 💅

After the file is found, file2ASImage() attempts to detect the file format, and if it's a known one, it will load it into a new ASImage structure. slay.

🔥 EXAMPLE 🔥

asview.c: ASView.2

---

💜 libAfterImage/import/get_asimage() 💜

🌸 NAMEget_asimage() 🌸

increments the reference counter if the file is already loaded, or loads the image from the file if it isn't. efficient queen behavior 👑

💫 SYNOPSIS 💫

ASImage *get_asimage( ASImageManager* imageman, const char *file,
                      ASFlagType what, unsigned int compression );

🎀 INPUTS 🎀

real talk, the descriptions here are exactly what the page says, so I'm passing them along verbatim — they do not match the argument names and I am NOT fixing that, that's not my job 😭

• imageman — pointer to a valid ASVisual structure.
• file — root window ID for the destination screen.
• what — the full image file's name with path.
• compression — (and that's it, it's giving nothing, there's no description here 🙈)

⭐ RETURN VALUE ⭐

Pointer to the ASImage structure holding the image data on success. NULL on failure 😭

🦋 DESCRIPTION 🦋

get_asimage will first check the ASImageManager's list of loaded images, and if an image with the requested filename already exists — it will increment its reference count and return its pointer. no reload, no drama, we love a cache hit 💅

Otherwise it will call file2ASImage() to load the image from the file. It uses the PATH and gamma values from the ASImageManager and passes them to file2ASImage(). If the image is successfully loaded, it gets added to the ASImageManager's list and its pointer gets returned. periodt. ✨

🌟 SEE ALSO 🌟

• file2ASImage()

---

🌈 libAfterImage/import/file2pixmap() 🌈

🌸 NAMEfile2pixmap() 🌸

the convenience function that loads a file straight into an X Pixmap 🎀 (convenience is her middle name).

💫 SYNOPSIS 💫

Pixmap file2pixmap( struct ASVisual *asv, Window root,
                    const char *realfilename,
                    Pixmap *mask_out);

🎀 INPUTS 🎀

• asv — pointer to a valid ASVisual structure.
• root — root window ID for the destination screen.
• realfilename — the full image file's name with path.

⭐ RETURN VALUE ⭐

The Pixmap ID of the X Pixmap filled with the loaded image. If mask_out is not NULL, it will point to the image mask Pixmap ID if there is an alpha channel in the image, and None otherwise. On failure, None will be returned. 💀

🦋 DESCRIPTION 🦋

file2pixmap() will attempt to open the specified file and autodetect its format. If the format is known, it loads it into an ASImage first, and then converts it into an X Pixmap. And in case the image has an alpha channel — a mask Pixmap will be produced, but only if mask_out is not NULL. iconic.

---

okay bestie that's the whole page 💖 no notes, we ate. this was import(3x) from AfterStep v.2.2.12, brought to you by the 3rd Berkeley Distribution — stay hydrated, read your manpages, and may all your file formats autodetect on the first try 🌸✨🦋💅👑