Rewrap comments to 80 columns in Source/platform/image-decoders/.

third_party/WebKit/Source/platform/image-decoders/gif/GIFImageReader.cpp

 /* -*- Mode: C; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
 /* ***** BEGIN LICENSE BLOCK *****
  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
  *
  * The contents of this file are subject to the Mozilla Public License Version
  * 1.1 (the "License"); you may not use this file except in compliance with
  * the License. You may obtain a copy of the License at
  * http://www.mozilla.org/MPL/
  *
  * Software distributed under the License is distributed on an "AS IS" basis,
@@ skipping 63 matching lines @@
 
 #include "platform/image-decoders/gif/GIFImageReader.h"
 
 #include "platform/Histogram.h"
 #include "wtf/PtrUtil.h"
 #include "wtf/Threading.h"
 #include <string.h>
 
 using blink::GIFImageDecoder;
 
-// GETN(n, s) requests at least 'n' bytes available from 'q', at start of state 's'.
+// GETN(n, s) requests at least 'n' bytes available from 'q', at start of state
+// 's'.
 //
-// Note, the hold will never need to be bigger than 256 bytes to gather up in the hold,
-// as each GIF block (except colormaps) can never be bigger than 256 bytes.
-// Colormaps are directly copied in the resp. global_colormap or dynamically allocated local_colormap.
-// So a fixed buffer in GIFImageReader is good enough.
-// This buffer is only needed to copy left-over data from one GifWrite call to the next
+// Note: the hold will never need to be bigger than 256 bytes, as each GIF block
+// (except colormaps) can never be bigger than 256 bytes. Colormaps are directly
+// copied in the resp. global_colormap or dynamically allocated local_colormap,
+// so a fixed buffer in GIFImageReader is good enough. This buffer is only
+// needed to copy left-over data from one GifWrite call to the next.
 #define GETN(n, s)          \
   do {                      \
     m_bytesToConsume = (n); \
     m_state = (s);          \
   } while (0)
 
 // Get a 16-bit value stored in little-endian format.
 #define GETINT16(p) ((p)[1] << 8 | (p)[0])
 
 // Send the data to the display front-end.
@@ skipping 92 matching lines @@
           break;
 
         default:
           break;
       }
     } while (irow > (m_frameContext->height() - 1));
   }
   return true;
 }
 
-// Perform Lempel-Ziv-Welch decoding.
-// Returns true if decoding was successful. In this case the block will have been completely consumed and/or rowsRemaining will be 0.
-// Otherwise, decoding failed; returns false in this case, which will always cause the GIFImageReader to set the "decode failed" flag.
+// Performs Lempel-Ziv-Welch decoding. Returns whether decoding was successful.
+// If successful, the block will have been completely consumed and/or
+// rowsRemaining will be 0.
 bool GIFLZWContext::doLZW(const unsigned char* block, size_t bytesInBlock) {
   const size_t width = m_frameContext->width();
 
   if (rowIter == rowBuffer.end())
     return true;
 
   for (const unsigned char* ch = block; bytesInBlock-- > 0; ch++) {
     // Feed the next byte into the decoder's 32-bit input buffer.
     datum += ((int)*ch) << bits;
     bits += 8;
@@ skipping 103 matching lines @@
       reinterpret_cast<const unsigned char*>(reader->getConsecutiveData(
           m_position, m_colors * BYTES_PER_COLORMAP_ENTRY, buffer));
   m_table.resize(m_colors);
   for (Table::iterator iter = m_table.begin(); iter != m_table.end(); ++iter) {
     *iter = SkPackARGB32NoCheck(255, srcColormap[0], srcColormap[1],
                                 srcColormap[2]);
     srcColormap += BYTES_PER_COLORMAP_ENTRY;
   }
 }
 
-// Perform decoding for this frame. frameDecoded will be true if the entire frame is decoded.
-// Returns false if a decoding error occurred. This is a fatal error and causes the GIFImageReader to set the "decode failed" flag.
-// Otherwise, either not enough data is available to decode further than before, or the new data has been decoded successfully; returns true in this case.
+// Performs decoding for this frame. frameDecoded will be true if the entire

[scroggo_chromium, 2016/10/04 15:36:00]

nit: This sentence feels awkward to me. Why not "Decode this frame"? (I think
it's less awkward above, when we are performing a specific decoding algorithm.

[Peter Kasting, 2016/10/04 16:01:58]

Rewrote this comment a bit.

+// frame is decoded. Returns true if decoding progressed further than before
+// without error, or there is insufficient new data to decode further.
+// Otherwise, a decoding error occurred; returns false in this case.
 bool GIFFrameContext::decode(blink::FastSharedBufferReader* reader,
                              blink::GIFImageDecoder* client,
                              bool* frameDecoded) {
   m_localColorMap.buildTable(reader);
 
   *frameDecoded = false;
   if (!m_lzwContext) {
     // Wait for more data to properly initialize GIFLZWContext.
     if (!isDataSizeDefined() || !isHeaderDefined())
       return true;
 
     m_lzwContext = wrapUnique(new GIFLZWContext(client, this));
     if (!m_lzwContext->prepareToDecode()) {
       m_lzwContext.reset();
       return false;
     }
 
     m_currentLzwBlock = 0;
   }
 
-  // Some bad GIFs have extra blocks beyond the last row, which we don't want to decode.
+  // Some bad GIFs have extra blocks beyond the last row, which we don't want to
+  // decode.
   while (m_currentLzwBlock < m_lzwBlocks.size() &&
          m_lzwContext->hasRemainingRows()) {
     size_t blockPosition = m_lzwBlocks[m_currentLzwBlock].blockPosition;
     size_t blockSize = m_lzwBlocks[m_currentLzwBlock].blockSize;
     if (blockPosition + blockSize > reader->size())
       return false;
 
     while (blockSize) {
       const char* segment = 0;
       size_t segmentLength = reader->getSomeData(segment, blockPosition);
       size_t decodeSize = std::min(segmentLength, blockSize);
       if (!m_lzwContext->doLZW(reinterpret_cast<const unsigned char*>(segment),
                                decodeSize))
         return false;
       blockPosition += decodeSize;
       blockSize -= decodeSize;
     }
     ++m_currentLzwBlock;
   }
 
-  // If this frame is data complete then the previous loop must have completely decoded all LZW blocks.
+  // If this frame is data complete then the previous loop must have completely
+  // decoded all LZW blocks.
   // There will be no more decoding for this frame so it's time to cleanup.
   if (isComplete()) {
     *frameDecoded = true;
     m_lzwContext.reset();
   }
   return true;
 }
 
-// Decode a frame.
-// This method uses GIFFrameContext:decode() to decode the frame; decoding error is reported to client as a critical failure.
-// Return true if decoding has progressed. Return false if an error has occurred.
+// Decodes a frame using GIFFrameContext:decode(). Returns true if decoding has
+// progressed, or false if an error has occurred.
 bool GIFImageReader::decode(size_t frameIndex) {
   blink::FastSharedBufferReader reader(m_data);
   m_globalColorMap.buildTable(&reader);
 
   bool frameDecoded = false;
   GIFFrameContext* currentFrame = m_frames[frameIndex].get();
 
   return currentFrame->decode(&reader, m_client, &frameDecoded) &&
          (!frameDecoded || m_client->frameComplete(frameIndex));
 }
@@ skipping 21 matching lines @@
   if (!len) {
     // No new data has come in since the last call, just ignore this call.
     return true;
   }
 
   if (len < m_bytesToConsume)
     return true;
 
   blink::FastSharedBufferReader reader(m_data);
 
-  // A read buffer of 16 bytes is enough to accomodate all possible reads for parsing.
+  // A read buffer of 16 bytes is enough to accomodate all possible reads for
+  // parsing.
   char readBuffer[16];
 
-  // This loop reads as many components from |m_data| as possible.
-  // At the beginning of each iteration, dataPosition will be advanced by m_bytesToConsume to
-  // point to the next component. len will be decremented accordingly.
+  // Read as many components from |m_data| as possible. At the beginning of each
+  // iteration, |dataPosition| is advanced by m_bytesToConsume to point to the
+  // next component. |len| is decremented accordingly.
   while (len >= m_bytesToConsume) {
     const size_t currentComponentPosition = dataPosition;
 
-    // Mark the current component as consumed. Note that currentComponent will remain pointed at this
-    // component until the next loop iteration.
+    // Mark the current component as consumed. Note that currentComponent will
+    // remain pointed at this component until the next loop iteration.
     dataPosition += m_bytesToConsume;
     len -= m_bytesToConsume;
 
     switch (m_state) {
       case GIFLZW:
         ASSERT(!m_frames.isEmpty());
-        // m_bytesToConsume is the current component size because it hasn't been updated.
+        // m_bytesToConsume is the current component size because it hasn't been
+        // updated.
         m_frames.last()->addLzwBlock(currentComponentPosition,
                                      m_bytesToConsume);
         GETN(1, GIFSubBlock);
         break;
 
       case GIFLZWStart: {
         ASSERT(!m_frames.isEmpty());
         m_frames.last()->setDataSize(static_cast<unsigned char>(
             reader.getOneByte(currentComponentPosition)));
         GETN(1, GIFSubBlock);
@@ skipping 79 matching lines @@
         const unsigned char* currentComponent =
             reinterpret_cast<const unsigned char*>(reader.getConsecutiveData(
                 currentComponentPosition, 2, readBuffer));
 
         size_t bytesInBlock = currentComponent[1];
         GIFState exceptionState = GIFSkipBlock;
 
         switch (*currentComponent) {
           case 0xf9:
             exceptionState = GIFControlExtension;
-            // The GIF spec mandates that the GIFControlExtension header block length is 4 bytes,
-            // and the parser for this block reads 4 bytes, so we must enforce that the buffer
-            // contains at least this many bytes. If the GIF specifies a different length, we
-            // allow that, so long as it's larger; the additional data will simply be ignored.
+            // The GIF spec mandates that the GIFControlExtension header block
+            // length is 4 bytes, and the parser for this block reads 4 bytes,
+            // so we must enforce that the buffer contains at least this many
+            // bytes. If the GIF specifies a different length, we allow that, so
+            // long as it's larger; the additional data will simply be ignored.
             bytesInBlock = std::max(bytesInBlock, static_cast<size_t>(4));
             break;
 
-          // The GIF spec also specifies the lengths of the following two extensions' headers
-          // (as 12 and 11 bytes, respectively). Because we ignore the plain text extension entirely
-          // and sanity-check the actual length of the application extension header before reading it,
-          // we allow GIFs to deviate from these values in either direction. This is important for
-          // real-world compatibility, as GIFs in the wild exist with application extension headers
-          // that are both shorter and longer than 11 bytes.
+          // The GIF spec also specifies the lengths of the following two
+          // extensions' headers (as 12 and 11 bytes, respectively). Because we
+          // ignore the plain text extension entirely and sanity-check the
+          // actual length of the application extension header before reading
+          // it, we allow GIFs to deviate from these values in either direction.
+          // This is important for real-world compatibility, as GIFs in the wild
+          // exist with application extension headers that are both shorter and
+          // longer than 11 bytes.
           case 0x01:
             // ignoring plain text extension
             break;
 
           case 0xff:
             exceptionState = GIFApplicationExtension;
             break;
 
           case 0xfe:
             exceptionState = GIFConsumeComment;
@@ skipping 34 matching lines @@
 
         // We ignore the "user input" bit.
 
         // NOTE: This relies on the values in the FrameDisposalMethod enum
         // matching those in the GIF spec!
         int disposalMethod = ((*currentComponent) >> 2) & 0x7;
         if (disposalMethod < 4) {
           currentFrame->setDisposalMethod(
               static_cast<blink::ImageFrame::DisposalMethod>(disposalMethod));
         } else if (disposalMethod == 4) {
-          // Some specs say that disposal method 3 is "overwrite previous", others that setting
-          // the third bit of the field (i.e. method 4) is. We map both to the same value.
+          // Some specs say that disposal method 3 is "overwrite previous",
+          // others that setting the third bit of the field (i.e. method 4) is.
+          // We map both to the same value.
           currentFrame->setDisposalMethod(
               blink::ImageFrame::DisposeOverwritePrevious);
         }
         currentFrame->setDelayTime(GETINT16(currentComponent + 1) * 10);
         GETN(1, GIFConsumeBlock);
         break;
       }
 
       case GIFCommentExtension: {
         const unsigned char currentComponent = static_cast<unsigned char>(
@@ skipping 24 matching lines @@
 
         if (m_state != GIFNetscapeExtensionBlock)
           GETN(1, GIFConsumeBlock);
         break;
       }
 
       // Netscape-specific GIF extension: animation looping.
       case GIFNetscapeExtensionBlock: {
         const int currentComponent = static_cast<unsigned char>(
             reader.getOneByte(currentComponentPosition));
-        // GIFConsumeNetscapeExtension always reads 3 bytes from the stream; we should at least wait for this amount.
+        // GIFConsumeNetscapeExtension always reads 3 bytes from the stream; we
+        // should at least wait for this amount.
         if (currentComponent)
           GETN(std::max(3, currentComponent), GIFConsumeNetscapeExtension);
         else
           GETN(1, GIFImageStart);
         break;
       }
 
       // Parse netscape-specific application extensions
       case GIFConsumeNetscapeExtension: {
         const unsigned char* currentComponent =
             reinterpret_cast<const unsigned char*>(reader.getConsecutiveData(
                 currentComponentPosition, 3, readBuffer));
 
         int netscapeExtension = currentComponent[0] & 7;
 
-        // Loop entire animation specified # of times. Only read the loop count during the first iteration.
+        // Loop entire animation specified # of times. Only read the loop count
+        // during the first iteration.
         if (netscapeExtension == 1) {
           m_loopCount = GETINT16(currentComponent + 1);
 
           // Zero loop count is infinite animation loop request.
           if (!m_loopCount)
             m_loopCount = blink::cAnimationLoopInfinite;
 
           GETN(1, GIFNetscapeExtensionBlock);
         } else if (netscapeExtension == 2) {
           // Wait for specified # of bytes to enter buffer.
 
           // Don't do this, this extension doesn't exist (isn't used at all)
-          // and doesn't do anything, as our streaming/buffering takes care of it all...
-          // See: http://semmix.pl/color/exgraf/eeg24.htm
+          // and doesn't do anything, as our streaming/buffering takes care of
+          // it all. See http://semmix.pl/color/exgraf/eeg24.htm .
           GETN(1, GIFNetscapeExtensionBlock);
         } else {
           // 0,3-7 are yet to be defined netscape extension codes
           return false;
         }
         break;
       }
 
       case GIFImageHeader: {
         unsigned height, width, xOffset, yOffset;
@@ skipping 58 matching lines @@
           m_screenWidth = std::max(m_screenWidth, xOffset + width);
         }
 
         // Inform the client of the final size.
         if (!m_sentSizeToClient && m_client &&
             !m_client->setSize(m_screenWidth, m_screenHeight))
           return false;
         m_sentSizeToClient = true;
 
         if (query == GIFImageDecoder::GIFSizeQuery) {
-          // The decoder needs to stop. Hand back the number of bytes we consumed from
-          // buffer minus 9 (the amount we consumed to read the header).
+          // The decoder needs to stop. Hand back the number of bytes we
+          // consumed from the buffer minus 9 (the amount we consumed to read
+          // the header).
           setRemainingBytes(len + 9);
           GETN(9, GIFImageHeader);
           return true;
         }
 
         addFrameIfNecessary();
         GIFFrameContext* currentFrame = m_frames.last().get();
 
         currentFrame->setHeaderDefined();
 
@@ skipping 14 matching lines @@
         // avoid jaggies at the transparency edges. We are
         // unprepared to deal with that, so don't display such
         // images progressively. Which means only the first
         // frame can be progressively displayed.
         // FIXME: It is possible that a non-transparent frame
         // can be interlaced and progressively displayed.
         currentFrame->setProgressiveDisplay(currentFrameIsFirstFrame());
 
         const bool isLocalColormapDefined = currentComponent[8] & 0x80;
         if (isLocalColormapDefined) {
-          // The three low-order bits of currentComponent[8] specify the bits per pixel.
+          // The three low-order bits of currentComponent[8] specify the bits
+          // per pixel.
           const size_t numColors = 2 << (currentComponent[8] & 0x7);
           currentFrame->localColorMap().setTablePositionAndSize(dataPosition,
                                                                 numColors);
           GETN(BYTES_PER_COLORMAP_ENTRY * numColors, GIFImageColormap);
           break;
         }
 
         GETN(1, GIFLZWStart);
         break;
       }
 
       case GIFImageColormap: {
         ASSERT(!m_frames.isEmpty());
         m_frames.last()->localColorMap().setDefined();
         GETN(1, GIFLZWStart);
         break;
       }
 
       case GIFSubBlock: {
         const size_t bytesInBlock = static_cast<unsigned char>(
             reader.getOneByte(currentComponentPosition));
         if (bytesInBlock)
           GETN(bytesInBlock, GIFLZW);
         else {
           // Finished parsing one frame; Process next frame.
           ASSERT(!m_frames.isEmpty());
-          // Note that some broken GIF files do not have enough LZW blocks to fully
-          // decode all rows but we treat it as frame complete.
+          // Note that some broken GIF files do not have enough LZW blocks to
+          // fully decode all rows; we treat this case as "frame complete".
           m_frames.last()->setComplete();
           GETN(1, GIFImageStart);
         }
         break;
       }
 
       case GIFDone: {
         m_parseCompleted = true;
         return true;
       }
@@ skipping 63 matching lines @@
   rowIter = rowBuffer.begin();
   rowsRemaining = m_frameContext->height();
 
   // Clearing the whole suffix table lets us be more tolerant of bad data.
   for (int i = 0; i < clearCode; ++i) {
     suffix[i] = i;
     suffixLength[i] = 1;
   }
   return true;
 }