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.