Embed an Image as GdkPixdata with gdk-pixbuf-pixdata

If a build you inherited still calls gdk-pixbuf-pixdata, you are maintaining a format GNOME has told everyone to stop using. Feed it an ordinary image and you get back a binary GdkPixdata file, with a repeatable check that the conversion succeeded. This is a legacy integration tool: current GNOME documentation says that the to-pixdata GResource preprocessing option has been deprecated since gdk-pixbuf 2.32, and recommends embedding PNG or SVG directly instead.

Allow about fifteen minutes. You need an image that the installed GDK Pixbuf loaders can read, a writable working directory, and the libgdk-pixbuf2.0-bin package. The examples do not need sudo. They write a new output file and leave the source image alone.

1. Check the installed command

Start with the local executable and package version. These are ordinary read-only checks:

$ command -v gdk-pixbuf-pixdata
/usr/bin/gdk-pixbuf-pixdata
$ dpkg-query -W -f='${Package} ${Version}\n' libgdk-pixbuf2.0-bin
libgdk-pixbuf2.0-bin 2.42.10+dfsg-3ubuntu3.3
$ gdk-pixbuf-pixdata --version
gdk-pixbuf-pixdata-3.0 version 2.42.10

The package version and exact output can differ on another Debian or Ubuntu release. Record them when a build or reproducibility problem matters. The installed help is also more complete than the November 2013 manpage on this host:

$ gdk-pixbuf-pixdata --help
Usage: gdk-pixbuf-pixdata-3.0 [options] [input-file] [output-file]
  -r, --rle                  compress the image data using RLE
  -h, --help                 show this help message
  -v, --version              print version informations
  --g-fatal-warnings         make warnings fatal (abort)

Checkpoint: if the command is missing, stop here and install the package through your normal system-management process. Do not copy a binary from another machine merely to make a build pass.

2. Choose a source image and a new destination

Use an explicit source path and a destination that does not already contain valuable data. GDK Pixbuf loads the image through its available image-format modules, so the filename extension alone does not prove that the file is readable.

$ SRC="$PWD/icon.png"
$ OUT="$PWD/icon.pixdata"
$ test -r "$SRC" && echo "source is readable"
source is readable
$ test ! -e "$OUT" && echo "destination is new"
destination is new

Replace icon.png with your real image. A path containing spaces is safe because the variables are quoted. The command does not resize the image or preserve it as PNG; it decodes the image and serialises the resulting pixbuf data.

3. Create an uncompressed GdkPixdata file

Pass the input first and output second. This writes binary data, so do not inspect it in a terminal or expect a text representation:

$ gdk-pixbuf-pixdata "$SRC" "$OUT"
$ printf 'exit status: %s\n' "$?"
exit status: 0
$ file "$OUT"
icon.pixdata: data

A successful run normally produces no progress message. The first bytes identify the serialised format, but file may only describe the result as generic data. Check that the file is non-empty and that its size is plausible for the image:

$ test -s "$OUT" && wc -c < "$OUT"
16408

The byte count is image-dependent. Do not paste the sample number into a test; the useful result is a positive size and exit status zero.

4. Use RLE when the result should be smaller

The installed 2.42.10 command provides --rle (or -r) to compress the image data with run-length encoding. Generate a separate file so the two representations can be compared:

$ RLE_OUT="$PWD/icon-rle.pixdata"
$ gdk-pixbuf-pixdata --rle "$SRC" "$RLE_OUT"
$ test -s "$RLE_OUT" && wc -c "$OUT" "$RLE_OUT"
16408 /path/to/icon.pixdata
 1577 /path/to/icon-rle.pixdata
17985 total

RLE is an encoding choice, not an image-quality setting. The output size depends on the pixels, and a small result is not proof that the file is valid. Keep the uncompressed file until your application or resource build has consumed the representation you chose.

5. Put the conversion into a safe build step

For a build, write to a temporary name in the same directory and rename it only after the command and a non-empty check succeed. This prevents a failed conversion from leaving a destination that looks complete:

$ tmp="$OUT.tmp.$$"
$ if gdk-pixbuf-pixdata --rle "$SRC" "$tmp" && test -s "$tmp"; then
>     mv -- "$tmp" "$OUT"
> else
>     printf 'conversion failed; keeping the previous output\n' >&2
>     rm -f -- "$tmp"
>     exit 1
> fi
$ test -s "$OUT" && echo "output ready"
output ready

The final mv replaces the old output only after a successful conversion. The cleanup rm targets the generated temporary file, not the source image. If you do not need replacement semantics, choose a fresh output name instead and avoid the cleanup branch.

6. Diagnose failures without changing system state

A missing or unreadable input returns a non-zero status and an error such as failed to load. Check the path and permission first:

$ ls -l -- "$SRC"
$ test -r "$SRC" && echo readable || echo 'not readable'
readable

If the output directory is not writable, choose a directory you own. Elevated privileges do not repair a malformed image, and running a conversion as root can create root-owned build artefacts that your normal user cannot replace.

With no usable positional arguments, this installed binary prints its usage and exits non-zero. The two-path form shown above is the reliable interface for scripts. Treat the local --help output as authoritative when it differs from an older manpage.

There is no meaningful undo operation for a newly generated file. To recover from a replacement, restore the previous output from your version-control checkout or backup. Do not delete the source image as part of cleanup.

7. Decide whether you should use it

GdkPixdata is a serialised pixbuf representation that lets an application create a pixbuf from embedded data. It can be appropriate when maintaining an older build which explicitly expects this format. For new GResource files, the upstream guidance is to embed PNG or SVG directly, because modern GResource handles those image formats without the deprecated to-pixdata preprocessing path.

Do not mistake this command for a general image converter. It does not produce PNG, JPEG or a human-readable C declaration, and it does not install the result into an application. The consumer must know how to load GdkPixdata, or the generated file is only an unused binary.