QImageConsumer(3qt)

📦 version 3.3.8b, in fedora 43, fedora 44

✨ QImageConsumer ✨

okay so bestie, this is the man page for QImageConsumer from the Qt 3 era — it lives in qimageconsumer.3qt and it's giving very "quietly essential plumbing" energy. let's get into it 💖

🌸 NAME 🌸

QImageConsumer — the abstraction that QImageDecoder leans on. that's it, that's the whole name. no cap.

🎀 SYNOPSIS 🎀

first things first, you gotta pull it in:

#include <qasyncimageio.h>

🫶 Public Members 🫶

here's the full roster of virtuals, and yeah every single one is pure virtual so you're writing all of them, no skipping:

  • virtual void end () = 0
  • virtual void changed ( const QRect & ) = 0
  • virtual void frameDone () = 0
  • virtual void frameDone ( const QPoint & offset, const QRect & rect ) = 0
  • virtual void setLooping ( int n ) = 0
  • virtual void setFramePeriod ( int milliseconds ) = 0
  • virtual void setSize ( int, int ) = 0

🦋 DESCRIPTION 🦋

so QImageConsumer is literally just an abstraction that QImageDecoder uses. that's the vibe. 🫶

and real talk — if you just wanna show an animated image, you probably do not need to hand-roll this. QMovie, or QLabel::setMovie(), are the easy-peasy ones and for most situations they do exactly what you want with animated images. no cap, just use those.

but if you're going deep? here's the mental model, and it's lowkey gorgeous:

  • a QImageConsumer consumes information about changes to the QImage that a QImageDecoder is maintaining.
  • think of the QImage as the model, or the source of the image data.
  • the QImageConsumer is a view of that data.
  • and the QImageDecoder is the controller orchestrating the whole relationship between the model and the view.

it's MVC but make it pixels. 💅

when would you actually reach for this? for example, if you were implementing a web browser with your own image loaders. iconic use case honestly.

See also: QImageDecoder, Graphics Classes, Image Processing Classes, and Multimedia Classes. go read those too bestie, i'm not gatekeeping.

💜 MEMBER FUNCTION DOCUMENTATION 💜

void QImageConsumer::changed ( const QRect & ) [pure virtual]

called when the given area of the image has changed. that's the whole job. ✨

void QImageConsumer::end () [pure virtual]

called when all the data from all the frames has been decoded and revealed as changed(). it's the finale, the last episode, the end credits. 😭

void QImageConsumer::frameDone () [pure virtual]

one of the two frameDone() functions gets called when a frame of an animated image has ended and been revealed as changed(). which one? surprise, it's this one or the other one.

when this function is called, the current image should be displayed.

and heads up: the decoder will not make any further changes to the image until the next call to QImageFormat::decode(). so like, do your thing, but the decoder is waiting on you. 🙈

void QImageConsumer::frameDone ( const QPoint & offset, const QRect & rect ) [pure virtual]

this is an overloaded member function, provided for convenience. it behaves essentially like the above function. (yes, it's the same energy, different args.)

one of the two frameDone() functions will be called when a frame of an animated image has ended and been revealed as changed().

when this one is called, the area rect in the current image should be moved by offset and displayed. got it? move then show. 👑

and again, same rule as before: the decoder will not make any further changes to the image until the next call to QImageFormat::decode().

void QImageConsumer::setFramePeriod ( int milliseconds ) [pure virtual]

notes that the frame about to be decoded should not be displayed until the given number of milliseconds after the time that this function is called.

but — and this is the important part — of course, the image may not have been decoded by then, in which case the frame should not be displayed until it is complete.

a value of -1 (the assumed default) means the image should be displayed even while it is only partially loaded. so like, -1 is the "show me anyway, i don't care, i'm impatient" setting. 💅

void QImageConsumer::setLooping ( int n ) [pure virtual]

called to indicate that the sequence of frames in the image should be repeated n times, including the sequence during decoding. so the decoding pass counts too, don't forget that part.

the numbers mean this:

  • 0 = Forever
  • 1 = Only display frames the first time through
  • 2 = Repeat once after first pass through images
  • etc.

and here's the tricky bit about making QImageDecoder actually do the looping: just delete it and pass the information to it again for decoding. (setLooping() will be called again, of course, but that can be ignored.) or, alternatively, keep copies of the changed areas at the ends of frames.

so: nuke and re-feed, or hoard those changed areas. your call, bestie. 🔥

void QImageConsumer::setSize ( int, int ) [pure virtual]

this function is called as soon as the size of the image has been determined. the moment it knows how big it is, it tells you. it's giving "i measured myself, here's the tea". 🎀

🌈 SEE ALSO 🌈

Copyright 1992-2007 Trolltech ASA, http://www.trolltech.com. See the license file included in the distribution for a complete license statement.

⭐ AUTHOR ⭐

Generated automatically from the source code. (yes, a robot wrote it. and honestly? it ate. 💅)

💀 BUGS 💀

if you find a bug in Qt, please report it as described in http://doc.trolltech.com/bughowto.html. Good bug reports help us to help you. Thank you. (genuinely though, good bug reports are a love language. 🫶)

the definitive Qt documentation is provided in HTML format; it is located at $QTDIR/doc/html and can be read using Qt Assistant or with a web browser. This man page is provided as a convenience for those users who prefer man pages, although this format is not officially supported by Trolltech. so like, it's the vibes version, not the canon version. 🌸

if you find errors in this manual page, please report them to qt-bugs@trolltech.com. please include the name of the manual page (qimageconsumer.3qt) and the Qt version (3.3.8).

no cap bestie: the whole thing is pure virtual, so if you're subclassing this, you're writing every single function. there is no "skip the boring ones." the compiler will simply end you. 😭

and that's the page!! written by Trolltech AS on 2 February 2007, for QImageConsumer(3qt), living its best life somewhere in the Qt 3.3.8 era. slay, periodt, go implement your callbacks. 💖✨🦋

📦 where this page comes from