image/gif: Mention the uselessness of BackgroundIndex in the docs

[AndreKR]

Go version: Go 1.8 (but this is a documentation issue)

Quick introduction to GIF disposal methods:
In an animated GIF, a disposal method can be set for each frame. It specifies to which state the canvas should be set before displaying the next frame when the current frame is finished being shown. There are three disposal methods, represented in image/gif by DisposalNone, DisposalBackground and DisposalPrevious.
DisposalNone means that the following frame is drawn on top of the current frame, so that transparent areas of the next frame continue to show this frame's content. DisposalPrevious means that the canvas is reset to the last frame that didn't have its disposal method set to DisposalPrevious. DisposalBackground means something else and I will come to that in a moment.

In Go, an animated GIF can be written by EncodeAll() in image/gif, which accepts a GIF struct that describes the animated GIF. This struct has a member BackgroundIndex byte whose inline documentation reads:

// BackgroundIndex is the background index in the global color table, for
// use with the DisposalBackground disposal method.
BackgroundIndex byte

This gives the impression that DisposalBackground means "the canvas is restored to the color given by BackgroundIndex.

However, in all modern browsers DisposalBackground is interpreted as "clear the canvas to fully transparent".

It turns out that this is indeed an ambiguity in the GIF89a specification which in the past has been interpreted as "clear to BackgroundIndex" but is apparently interpreted as "clear to transparent" since about 15 years ago, as this comment from the Mozilla bugtracker shows.

Since I just spent an hour figuring out why Chrome (as I thought) doesn't reset the canvas to BackgroundIndex, I would appreciate if the fact that BackgroundIndex is essentially ignored by all browsers would be mentioned in the docs.

[bradfitz]

Marking for Go 1.10, but if you want to shoot something off soon, it could make Go 1.9 if it's docs only.

[gopherbot]

CL https://golang.org/cl/46091 mentions this issue.

[gopherbot]

CL https://golang.org/cl/49019 mentions this issue.