In response to Christophe's concerns, I have updated the API example to
show use of GetFirstImageInList() after using AppendImageToList(). I
also improved the documentation for each of the image list APIs. If
something is missing, or not clear, please let me know.
The image list APIs have existed roughly as is since at least January
2002 and many were originally written by John Cristy (ImageMagick
author). In fact, the functions which appeared in 2002 were already
elsewhere in the code and gathered/renamed to create list.c.
There is good reason to be confused regarding an image list given that
although each entry in an image list is one image frame, some file
formats (e.g. GIF) may contain many frames. It is possible (and often
reasonable) to conjoin frames from many files into one list. So frames
from formats which only support one frame per file could be mixed with
some/all of the frames from GIF files. When dealing with GIF files, it
makes most sense that all frames correspond to the same GIF file.
Appending to a list becomes slower and slower as the list gets longer
and longer if the list reference is not the tail of the list. It is
convenient if the code which recently appended to the list
uses GetFirstImageInList() to return the head of the list to higher
level consumers. It appears to me that ReadGIFImage() does return the
head of the list.
Bob
On 7/28/26 09:34, Beauregard,Christophe (ECCC) wrote:
>GraphicsMagick rarely changes its API behavior.
Agreed, that's 100% why we migrated to it.
>Use GetFirstImageInList() when the pointer to the first image in the
list is needed.
The problem I think I'm having with this change is it's unclear that
the first image in the list is needed for WriteImage(), because you
have an API that's inconsistent about when any list element can be a
shorthand for the entire list.
For example the call:
GetImageListLength(thumbnails)
Always returns 6 whether it's before or after the:
thumbnails=GetFirstImageInList(thumbnails);
Since the list functions (only the list functions?) internally rewind
to the beginning of the list before doing what they do.
Clearly we're passing a 6 image list to GetImages(), and the list code
knows it's a 6 image list, but... WriteImage() (and presumably most
other API calls) ignore those list API semantics. This is misleading.
I'm not saying the behaviour is right or wrong, but at minimum the API
documentation really should highlight the distinction between
functions which operate on image lists (per list API semantics) and
functions which only operate on the rest of the image list.
c.
------------------------------------------------------------------------
*From:* Bob Friesenhahn <[email protected]>
*Sent:* Tuesday, July 28, 2026 09:46
*To:* Beauregard,Christophe (ECCC) <[email protected]>;
[email protected] <[email protected]>
*Subject:* Re: Bug#1142941: (no subject)
You don't often get email from [email protected]. Learn
why this is important <https://aka.ms/LearnAboutSenderIdentification>
It seems that the API demo stopped working due to a documented
behavior change for the GraphicsMagick 1.3.40 release:
API Updates:
* AppendImageToList() now updates the image list pointer to be the
image which was just added. Use GetFirstImageInList() when the
pointer to the first image in the list is needed.
GraphicsMagick rarely changes its API behavior. This change was made
due to observing performance issues with many (e.g. 10k) images in a
list. It is much more efficient to remember the end of the list while
appending additional frames to the list rather than re-starting from
the beginning.
Bob
On 7/28/26 08:34, Christophe Beauregard wrote:
The following change to the demo code fixes the problem (which is
what ConvertImageCommand() does):
$ diff demo.c.bak demo.c
68a69
> thumbnails=GetFirstImageInList(thumbnails);
Presumably some change internally stopped the GIF coder from finding
the head of the list, or the Append call changed the ordering, or
something?
$ sh test.sh
libgraphicsmagick1-dev 1.4+really1.3.45+hg17696-1
Reading 1.png ... 1 frames
Reading 2.png ... 1 frames
Reading 3.png ... 1 frames
Reading 4.png ... 1 frames
Reading 5.png ... 1 frames
Reading 6.png ... 1 frames
Writing out.gif ... 6 frames
out.gif[0] GIF 106x80+0+0 PseudoClass 256c 8-bit 9.1Ki 0.000u
0m:0.000000s
out.gif[1] GIF 106x80+0+0 PseudoClass 256c 8-bit 9.1Ki 0.000u
0m:0.000034s
out.gif[2] GIF 106x80+0+0 PseudoClass 256c 8-bit 9.1Ki 0.000u
0m:0.000036s
out.gif[3] GIF 106x80+0+0 PseudoClass 128c 8-bit 9.1Ki 0.000u
0m:0.000034s
out.gif[4] GIF 106x80+0+0 PseudoClass 256c 8-bit 9.1Ki 0.000u
0m:0.000034s
out.gif[5] GIF 106x80+0+0 PseudoClass 256c 8-bit 9.1Ki 0.000u
0m:0.000035s
