hopefully avoid coverity complaining about a float vs int comparison
[imager.git] / design / tags.txt
1 Currently when writing an animated gif you can do:
2
3   Imager->write_multi({ type=>'gif', file=>'foo.gif',
4                         gif_delays => [ (10) x @images ] },
5                       @images);
6
7 and it will write out the images in @images with the given delay
8 between each image.
9
10 Now let's say we decide that all options are to be supplied in tags
11 instead of as parameters, this includes things like the jpegquality
12 (if possible) and tiff text tags.
13
14 The problem with this is that we're making it harder to write the
15 image, rather than supplying the parameters to write*() the user needs
16 to go through an set tags:
17
18   $_->addtag(name=>'gif_delay', value=>10) for @images;
19   Imager->write_multi({ type=>'gif', file=>'foo.gif'},
20                       @images);
21
22 It's worse if the user needs to set more options:
23
24   $_->addtag(name=>'gif_delay', value=>10) for @images;
25   $_->addtag(name=>'gif_user_input', value=>1) for @images;
26   Imager->write_multi({ type=>'gif', file=>'foo.gif'},
27                       @images);
28
29 Now we could add a function to simplify this:
30
31   $_->addtags(gif_delay=>10, gif_user_input=>1) for @images;
32   Imager->write_multi({ type=>'gif', file=>'foo.gif'},
33                       @images);
34
35 but consider how we can preserve some of the existing interface.
36
37 The option I was considering was to have the write*() methods set any
38 parameters that have the file type as a prefix in the write call, as
39 tags in the image, hence:
40
41   Imager->write_multi({ type=>'gif', file=>'foo.gif',
42                         gif_delay => [ (10) x @images ],
43                         gif_user_input => [ (1) x @images ] },
44                       @images);
45
46 If the value provided isn't an array reference, we could expand that to the number of images, so:
47
48   Imager->write_multi({ type=>'gif', file=>'foo.gif',
49                         gif_delay => 10,
50                         gif_user_input => 1 },
51                       @images);
52
53 This also applies nicely to TIFFs:
54
55   Imager->write_multi({ type=>'tiff', file=>'foo.tiff',
56                         tiff_pagename => [ map "Page $_", 1 .. @images ],
57                         tiff_documentname => "My New Document" },
58                       @images);
59
60 Now the names aren't going to be completely compatible between the old
61 interface and the new, since the gif names at least tend to be
62 plurals, but we do preserve the ease of use of the interface, making
63 it more DWIM than a "set tags then write" interface.
64
65 The main problem with this interface is we're modifying images that
66 we're meant to be writing to a file, which really shouldn't require
67 modifying the images.
68
69 We discussed some of this in IRC a while ago, but didn't come to any
70 decisions.