# TIP 98: Adding Transparency Compositing Rules to Photo Images
	Author:		Donal K. Fellows <fellowsd@cs.man.ac.uk>
	Created:	09-Jun-2001
	Type:		Project
	State:		Final
	Vote:		Done
	Tcl-Version:	8.4
	Post-History:	
	Tk-Ticket:	566765
-----

# Abstract

This TIP adds compositing rules to Tk's photo images to give
programmers better control over what happens when two transparent
images are combined.  This TIP also allows for several frames of an
animated GIF file to be correctly displayed in an image even when the
transparent area is not constant.

# Rationale

This is a TIP that is inspired by the tkchat application in Tcllib,
and in particular by the image used to represent the LOL smiley.  The
problem with this image is that its transparent area changes over
time, and this is caused by the fact that _Tk\_PhotoPutBlock\(\)_ only
allows one way of compositing a block with an image; it behaves as if
the data being added was on a sheet of cel \(the material used to make
hand-drawn animated cartoons\) allowing for sophisticated layering
effects.  Unfortunately, for many applications \(and animated GIF
images are definitely among these\) this sophistication works against
us.  In a GIF image, transparency is treated not as extra information
that is added to each pixel's colour, but rather as a special colour;
a pixel cannot be, for example, red and transparent at the same time.
Support for this requires a different \(and indeed simpler\) kind of
compositing rule.  And of course, once you have such a facility in the
underlying C code, it should be exposed to scripts.

There are other kinds of compositing rule \(for example, acting like
the added block is placed under the image, and many others\) but this
TIP does not propose adding anything other than a way to chose between
the current behaviour and the behaviour required for supporting GIF
animation, in the belief that those two compositing rules are the ones
most useful to programmers, and that once the general facility is
there, the other rules will be relatively easy to add in the future.

# Specification

This TIP adds a _compositingRule_ argument to _Tk\_PhotoPutBlock_
\(and _Tk\_PhotoPutZoomedBlock_\) to allow selection between the
current behaviour \(overlaying\) and the other one I wish to support
\(setting/overriding.\)  The permitted values of this argument will be
_TK\_PHOTO\_COMPOSITE\_OVERLAY_ \(the currently implemented behaviour\)
and _TK\_PHOTO\_COMPOSITE\_SET_ \(the behaviour required to support GIF
file animation.\)

At the Tcl level, when copying from one image to another \(the other
photo image subcommands do not currently support transparency at all\)
the _photo get_ will take an extra option _-compositingrule_ to
allow selection of the compositing rule.  The permitted values of this
option will be _overlay_ and _set_ by analogy with the values
described above.

# Implementation Notes

Proposed implementation patch:
<https://sourceforge.net/tracker/index.php?func=detail&aid=566765&group\_id=12997&atid=312997>

The proposed implementation of this TIP naturally includes
backward-compatibility functions that allow pre-compiled extensions to
continue to operate without recompilation \(provided they use Stubs for
linking.\)  Furthermore, extension authors can also define the symbol
_USE\_COMPOSITELESS\_PHOTO\_PUT\_BLOCK_ when compiling and have
source-level compatibility with the old functions.

The proposed implementation also creates _TkSubtractRegion_ as a new
internal function; it is the analogue of _XSubtractRegion_ as
_TkIntersectRegion_ is the analogue of _XIntersectRegion_.  It
might be useful to other parts of the core that manipulate regions.

Both the PPM and GIF file readers use the _set_ compositing rule,
PPM because the format does not support transparency \(and _set_
should at least theoretically be faster\) and GIF because it is
required semantically.  Other image formats are not required to do
this, of course.  The _$img put $data_ photo image subcommand uses
_set_ compositing because it does not support transparency.

# Copyright

This document is placed in the public domain.

