TileComponentWindow.h

Go to the documentation of this file.

/*
 *    Copyright (C) 2016-2026 Grok Image Compression Inc.
 *
 *    This source code is free software: you can redistribute it and/or  modify
 *    it under the terms of the GNU Affero General Public License, version 3,
 *    as published by the Free Software Foundation.
 *
 *    This source code is distributed in the hope that it will be useful,
 *    but WITHOUT ANY WARRANTY; without even the implied warranty of
 *    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *    GNU Affero General Public License for more details.
 *
 *    You should have received a copy of the GNU Affero General Public License
 *    along with this program.  If not, see <http://www.gnu.org/licenses/>.
 *
 */
 
/*
Various coordinate systems are used to describe regions in the tile component buffer.
 
1) Canvas coordinates:  JPEG 2000 global image coordinates.
 
2) Tile component coordinates: canvas coordinates with sub-sampling applied
 
3) Band coordinates: coordinates relative to a specified sub-band's origin
 
4) Buffer coordinates: coordinate system where all resolutions are translated
 to common origin (0,0). If each code block is translated relative to the origin of the
resolution that **it belongs to**, the blocks are then all in buffer coordinate system
 
Note: the name of any method or variable returning non canvas coordinates is appended
with "REL", to signify relative coordinates.
 
*/
 
#pragma once
 
#include <algorithm>
#include <type_traits>
 
#include "ResWindow.h"
#include "ISparseCanvas.h"
#include "PostDecodeFilters.h"
#include "PostDecodeFiltersOJPH.h"
 
namespace grk
{

struct ITileComponentWindow
{
  virtual ~ITileComponentWindow() = default;
 
  // Allocation
  virtual bool alloc() = 0;
 
  // Geometry
  virtual Rect32 bounds() const = 0;
  virtual Rect32 unreducedBounds() const = 0;
  virtual const Rect32* getBandWindowPadded(uint8_t resno,
                                            t1::eBandOrientation orientation) const = 0;
  virtual void toRelativeCoordinates(uint8_t resno, t1::eBandOrientation orientation,
                                     uint32_t& offsetx, uint32_t& offsety) const = 0;
 
  // Data transfer (type-erased)
  virtual void transferData(void** data, uint32_t* stride) = 0;
  virtual void attachData(void* data, uint32_t stride) = 0;
 
  // Buffer access (type-erased)
  virtual uint32_t highestResStride() const = 0;
  virtual uint64_t stridedArea() const = 0;
 
  // Post-process: T1 always outputs int32_t.
  // int32 window writes int32 to band buffers; int16 window narrows to int16.
  virtual void postProcessBlock(int32_t* srcData, t1::DecompressBlockExec* block,
                                ISparseCanvas<int32_t>* regionWindow) = 0;
  virtual void postProcessBlockHT(int32_t* srcData, t1::DecompressBlockExec* block, uint16_t stride,
                                  ISparseCanvas<int32_t>* regionWindow) = 0;
};
 
template<class T>
constexpr T getFilterPad(bool lossless)
{
  return lossless ? 1 : 2;
}
 
template<typename T>
struct TileComponentWindowBase : public ITileComponentWindow
{
  TileComponentWindowBase(bool isCompressor, bool lossless, bool wholeTileDecompress,
                          Rect32 unreducedTileComp, Rect32 reducedTileComp,
                          Rect32 unreducedImageCompWindow, uint8_t numresolutions,
                          uint8_t reducedNumResolutions)
      : unreducedBounds_(unreducedTileComp), bounds_(reducedTileComp), compress_(isCompressor),
        wholeTileDecompress_(wholeTileDecompress)
  {
    assert(reducedNumResolutions > 0);
    auto currentRes = unreducedTileComp;
    for(uint8_t i = 0; i < numresolutions; ++i)
    {
      bool finalResolution = i == numresolutions - 1;
      ResSimple r(currentRes, finalResolution);
      resolution_.push_back(r);
      if(!finalResolution)
        currentRes = ResSimple::getBandWindow(1, 0, currentRes);
    }
    std::reverse(resolution_.begin(), resolution_.end());
 
    // generate bounds
    unreducedBounds_ = unreducedImageCompWindow.intersection(unreducedBounds_);
    assert(unreducedBounds_.valid());
    bounds_ = unreducedImageCompWindow.scaleDownCeilPow2(
        (uint8_t)(numresolutions - reducedNumResolutions));
    bounds_ = bounds_.intersection(reducedTileComp);
    assert(bounds_.valid());
 
    // fill resolutions vector
    auto tileCompAtRes = resolution_[reducedNumResolutions - 1];
    auto tileCompAtLowerRes =
        reducedNumResolutions > 1 ? resolution_[reducedNumResolutions - 2] : ResSimple();
    // create resolution buffers
    auto highestResWindow = new ResWindow<T>(
        numresolutions, (uint8_t)(reducedNumResolutions - 1U), nullptr, tileCompAtRes,
        tileCompAtLowerRes, bounds_, unreducedBounds_, unreducedTileComp,
        wholeTileDecompress ? 0 : getFilterPad<uint32_t>(lossless));
    // setting top level prevents allocation of tileCompBandWindows buffers
    if(!useBandWindows())
      highestResWindow->disableBandWindowAllocation();
 
    // create windows for all resolutions except highest resolution
    for(uint8_t resno = 0; resno < reducedNumResolutions - 1; ++resno)
    {
      // resolution window ==  LL band window of next highest resolution
      auto resWindow =
          ResSimple::getBandWindow((uint8_t)(numresolutions - 1 - resno), 0, unreducedBounds_);
      resWindows.push_back(
          new ResWindow<T>(numresolutions, resno,
                           useBandWindows() ? nullptr : highestResWindow->getResWindowBufferREL(),
                           resolution_[resno], resno > 0 ? resolution_[resno - 1] : ResSimple(),
                           resWindow, unreducedBounds_, unreducedTileComp,
                           wholeTileDecompress ? 0 : getFilterPad<uint32_t>(lossless)));
    }
    resWindows.push_back(highestResWindow);
  }
  virtual ~TileComponentWindowBase()
  {
    for(auto& b : this->resWindows)
      delete b;
  }

  Rect32 bounds() const override
  {
    return bounds_;
  }
  Rect32 unreducedBounds() const override
  {
    return unreducedBounds_;
  }
  bool alloc() override
  {
    return std::all_of(resWindows.begin(), resWindows.end(),
                       [this](const auto& b) { return b->alloc(!compress_); });
  }
 
protected:
  bool useBandWindows() const
  {
    return !this->wholeTileDecompress_;
  }
  // windowed bounds for windowed decompress, otherwise full bounds
  std::vector<ResWindow<T>*> resWindows;
  /******************************************************/
  // decompress: unreduced/reduced image component window
  // compress:  unreduced/reduced tile component
  Rect32 unreducedBounds_;
  Rect32 bounds_;
  /******************************************************/
 
  std::vector<ResSimple> resolution_;
  bool compress_;
  bool wholeTileDecompress_;
};
 
template<typename T>
struct TileComponentWindow : public TileComponentWindowBase<T>
{
  typedef Buffer2d<T, AllocatorAligned> Buf2dAligned;
  TileComponentWindow(bool isCompressor, bool lossless, bool wholeTileDecompress,
                      Rect32 unreducedTileComp, Rect32 reducedTileComp,
                      Rect32 unreducedImageCompWindow, uint8_t numresolutions,
                      uint8_t reducedNumResolutions)
      : TileComponentWindowBase<T>(isCompressor, lossless, wholeTileDecompress, unreducedTileComp,
                                   reducedTileComp, unreducedImageCompWindow, numresolutions,
                                   reducedNumResolutions)
 
  {}
  ~TileComponentWindow() override = default;

  void toRelativeCoordinates(uint8_t resno, t1::eBandOrientation orientation, uint32_t& offsetx,
                             uint32_t& offsety) const override
  {
    assert(resno < this->resolution_.size());
 
    auto res = this->resolution_[resno];
    auto band = res.tileBand + getBandIndex(resno, orientation);
 
    // get offset relative to band
    assert(offsetx >= band->x0);
    assert(offsety >= band->y0);
    offsetx -= band->x0;
    offsety -= band->y0;
 
    if(useBufferCoordinatesForCodeblock() && resno > 0)
    {
      auto resLower = this->resolution_[resno - 1U];
 
      if(orientation & 1)
        offsetx += resLower.width();
      if(orientation & 2)
        offsety += resLower.height();
    }
  }
  template<typename F>
  void postProcess(Buf2dAligned& src, uint8_t resno, t1::eBandOrientation bandOrientation,
                   t1::DecompressBlockExec* block)
  {
    Buffer2d<int32_t, AllocatorAligned> dst;
    dst = getCodeBlockDestWindowREL(resno, bandOrientation);
    dst.copyFrom<F>(src, F(block));
  }
 
  // Cross-type post-process: narrows wider source (e.g., int32_t) into T band buffer
  template<typename SrcT, template<class> class SrcA, typename F>
  void postProcessNarrow(Buffer2d<SrcT, SrcA>& src, uint8_t resno,
                         t1::eBandOrientation bandOrientation, t1::DecompressBlockExec* block)
  {
    Buf2dAligned dst;
    dst = getCodeBlockDestWindowREL(resno, bandOrientation);
    dst.template copyFromNarrow<SrcT, SrcA, F>(&src, F(block));
  }

  const Buf2dAligned* getBandWindowBufferPaddedREL(uint8_t resno,
                                                   t1::eBandOrientation orientation) const
  {
    assert(resno < this->resolution_.size());
    assert(resno > 0 || orientation == t1::BAND_ORIENT_LL);
 
    if(resno == 0 && (this->compress_ || this->wholeTileDecompress_))
      return this->resWindows[0]->getResWindowBufferREL();
 
    return this->resWindows[resno]->getBandWindowBufferPaddedREL(orientation);
  }

  const Buffer2dSimple<T> getBandWindowBufferPaddedSimple(uint8_t resno,
                                                          t1::eBandOrientation orientation) const
  {
    assert(resno < this->resolution_.size());
    assert(resno > 0 || orientation == t1::BAND_ORIENT_LL);
 
    if(resno == 0 && (this->compress_ || this->wholeTileDecompress_))
      return this->resWindows[0]->getResWindowBufferSimple();
 
    return this->resWindows[resno]->getBandWindowBufferPaddedSimple(orientation);
  }

  const Buffer2dSimple<float>
      getBandWindowBufferPaddedSimpleF(uint8_t resno, t1::eBandOrientation orientation) const
  {
    assert(resno < this->resolution_.size());
    assert(resno > 0 || orientation == t1::BAND_ORIENT_LL);
 
    if(resno == 0 && (this->compress_ || this->wholeTileDecompress_))
      return this->resWindows[0]->getResWindowBufferSimpleF();
 
    return this->resWindows[resno]->getBandWindowBufferPaddedSimpleF(orientation);
  }

  const Rect32* getBandWindowPadded(uint8_t resno, t1::eBandOrientation orientation) const override
  {
    return this->resWindows[resno]->getBandWindowPadded(orientation);
  }
  /*
   * Get intermediate split window
   *
   * @param orientation 0 for upper split window, and 1 for lower split window
   */
  const Buf2dAligned* getResWindowBufferSplitREL(uint8_t resno, eSplitOrientation orientation) const
  {
    assert(resno > 0 && resno < this->resolution_.size());
 
    return this->resWindows[resno]->getResWindowBufferSplitREL(orientation);
  }
  /*
   * Get intermediate split window simple buffer
   *
   * @param orientation 0 for upper split window, and 1 for lower split window
   */
  const Buffer2dSimple<T> getResWindowBufferSplitSimple(uint8_t resno,
                                                        eSplitOrientation orientation) const
  {
    return getResWindowBufferSplitREL(resno, orientation)->simple();
  }
 
  /*
   * Get intermediate split window simpleF buffer
   *
   * @param orientation 0 for upper split window, and 1 for lower split window
   */
  const Buffer2dSimple<float> getResWindowBufferSplitSimpleF(uint8_t resno,
                                                             eSplitOrientation orientation) const
  {
    return getResWindowBufferSplitREL(resno, orientation)->simpleF();
  }

  const Buf2dAligned* getResWindowBufferREL(uint8_t resno) const
  {
    return this->resWindows[resno]->getResWindowBufferREL();
  }

  const Buffer2dSimple<T> getResWindowBufferSimple(uint8_t resno) const
  {
    return getResWindowBufferREL(resno)->simple();
  }

  const Buffer2dSimple<float> getResWindowBufferSimpleF(uint8_t resno) const
  {
    return getResWindowBufferREL(resno)->simpleF();
  }

  uint32_t getResWindowBufferHighestStride(void) const
  {
    return getResWindowBufferHighestREL()->getStride();
  }

  Buffer2dSimple<T> getResWindowBufferHighestSimple(void) const
  {
    return getResWindowBufferHighestREL()->simple();
  }

  Buffer2dSimple<float> getResWindowBufferHighestSimpleF(void) const
  {
    return getResWindowBufferHighestREL()->simpleF();
  }
 
  // set data to buf without owning it
  void attach(T* buffer, uint32_t stride)
  {
    getResWindowBufferHighestREL()->attach(buffer, stride);
  }
  // transfer data to buf, and cease owning it
  void transfer(T** buffer, uint32_t* stride)
  {
    getResWindowBufferHighestREL()->transfer(buffer, stride);
  }
 
  // --- ITileComponentWindow virtual method overrides ---
 
  void transferData(void** data, uint32_t* stride) override
  {
    T* typedData = nullptr;
    transfer(&typedData, stride);
    *data = typedData;
  }
  void attachData(void* data, uint32_t stride) override
  {
    attach(static_cast<T*>(data), stride);
  }
  uint32_t highestResStride() const override
  {
    return getResWindowBufferHighestStride();
  }
  uint64_t stridedArea() const override
  {
    auto win = getResWindowBufferHighestREL();
    return (uint64_t)win->getStride() * win->height();
  }
  void postProcessBlock(int32_t* srcData, t1::DecompressBlockExec* block,
                        ISparseCanvas<int32_t>* regionWindow) override;
  void postProcessBlockHT(int32_t* srcData, t1::DecompressBlockExec* block, uint16_t stride,
                          ISparseCanvas<int32_t>* regionWindow) override;
 
private:
  const Buf2dAligned* getCodeBlockDestWindowREL(uint8_t resno,
                                                t1::eBandOrientation orientation) const
  {
    return (useBufferCoordinatesForCodeblock()) ? getResWindowBufferHighestREL()
                                                : getBandWindowBufferPaddedREL(resno, orientation);
  }
  Buf2dAligned* getResWindowBufferHighestREL(void) const
  {
    return this->resWindows.back()->getResWindowBufferREL();
  }
  bool useBufferCoordinatesForCodeblock() const
  {
    return this->compress_ || !this->wholeTileDecompress_;
  }
  uint8_t getBandIndex(uint8_t resno, t1::eBandOrientation orientation) const
  {
    return resno > 0 ? (uint8_t)orientation - 1 : 0;
  }
};
 
// ---------- postProcessBlock / postProcessBlockHT out-of-class definitions ----------
 
template<typename T>
void TileComponentWindow<T>::postProcessBlock(int32_t* srcData, t1::DecompressBlockExec* block,
                                              ISparseCanvas<int32_t>* regionWindow)
{
  auto cblk = block->cblk;
  bool empty = cblk->dataChunksEmpty();
  uint32_t x = block->x;
  uint32_t y = block->y;
  toRelativeCoordinates(block->resno, block->bandOrientation, x, y);
  auto blockBounds = Rect32(x, y, x + cblk->width(), y + cblk->height());
 
  if constexpr(std::is_same_v<T, int16_t>)
  {
    // 16-bit narrowing path: int32 T1 output -> int16 band buffers
    auto src = Buffer2d<int32_t, AllocatorAligned>(srcData, false, cblk->width(),
                                                   (uint16_t)cblk->width(), cblk->height());
    if(!empty && !regionWindow)
    {
      src.setRect(blockBounds);
      if(block->qmfbid == 0)
      {
        // Irreversible 9/7: dequantize and narrow to int16
        if(block->roishift)
          this->template postProcessNarrow<int32_t, AllocatorAligned, t1::NarrowRoiScaleFilter16>(
              src, block->resno, block->bandOrientation, block);
        else
          this->template postProcessNarrow<int32_t, AllocatorAligned, t1::NarrowScaleFilter16>(
              src, block->resno, block->bandOrientation, block);
      }
      else
      {
        // Reversible 5/3: shift and narrow to int16
        if(block->roishift)
          this->template postProcessNarrow<int32_t, AllocatorAligned, t1::NarrowRoiShiftFilter>(
              src, block->resno, block->bandOrientation, block);
        else
          this->template postProcessNarrow<int32_t, AllocatorAligned, t1::NarrowShiftFilter>(
              src, block->resno, block->bandOrientation, block);
      }
    }
  }
  else
  {
    // Standard int32 path
    auto src = Buffer2d<T, AllocatorAligned>(srcData, false, cblk->width(), (uint16_t)cblk->width(),
                                             cblk->height());
    if(!empty)
    {
      if(regionWindow)
      {
        if(block->roishift)
        {
          if(block->qmfbid == 1)
            src.template copyFrom<t1::RoiShiftFilter<T>>(src, t1::RoiShiftFilter<T>{block});
          else
            src.template copyFrom<t1::RoiScaleFilter<T>>(src, t1::RoiScaleFilter<T>{block});
        }
        else
        {
          if(block->qmfbid == 1)
            src.template copyFrom<t1::ShiftFilter<T>>(src, t1::ShiftFilter<T>{block});
          else
            src.template copyFrom<t1::ScaleFilter<T>>(src, t1::ScaleFilter<T>{block});
        }
      }
      else
      {
        src.setRect(blockBounds);
        if(block->roishift)
        {
          if(block->qmfbid == 1)
            postProcess<t1::RoiShiftFilter<T>>(src, block->resno, block->bandOrientation, block);
          else
            postProcess<t1::RoiScaleFilter<T>>(src, block->resno, block->bandOrientation, block);
        }
        else
        {
          if(block->qmfbid == 1)
            postProcess<t1::ShiftFilter<T>>(src, block->resno, block->bandOrientation, block);
          else
            postProcess<t1::ScaleFilter<T>>(src, block->resno, block->bandOrientation, block);
        }
      }
    }
    if(regionWindow)
      regionWindow->write(block->resno, blockBounds, empty ? nullptr : srcData, 1,
                          blockBounds.width());
  }
}
 
template<typename T>
void TileComponentWindow<T>::postProcessBlockHT(int32_t* srcData, t1::DecompressBlockExec* block,
                                                uint16_t stride,
                                                ISparseCanvas<int32_t>* regionWindow)
{
  auto cblk = block->cblk;
  bool empty = cblk->dataChunksEmpty();
  uint32_t x = block->x;
  uint32_t y = block->y;
  toRelativeCoordinates(block->resno, block->bandOrientation, x, y);
  auto blockBounds = Rect32(x, y, x + cblk->width(), y + cblk->height());
 
  if constexpr(std::is_same_v<T, int16_t>)
  {
    // 16-bit narrowing path: int32 T1 output -> int16 band buffers
    auto src =
        Buffer2d<int32_t, AllocatorAligned>(srcData, false, cblk->width(), stride, cblk->height());
    if(!empty && !regionWindow)
    {
      src.setRect(blockBounds);
      if(block->qmfbid == 0)
      {
        // Irreversible 9/7: dequantize and narrow to int16 (OJPH sign-magnitude)
        if(block->roishift)
          this->template postProcessNarrow<int32_t, AllocatorAligned,
                                           t1::ojph::NarrowRoiScaleOJPHFilter16>(
              src, block->resno, block->bandOrientation, block);
        else
          this->template postProcessNarrow<int32_t, AllocatorAligned,
                                           t1::ojph::NarrowScaleOJPHFilter16>(
              src, block->resno, block->bandOrientation, block);
      }
      else
      {
        // Reversible 5/3: shift and narrow to int16
        if(block->roishift)
          this->template postProcessNarrow<int32_t, AllocatorAligned,
                                           t1::ojph::NarrowRoiShiftOJPHFilter>(
              src, block->resno, block->bandOrientation, block);
        else
          this->template postProcessNarrow<int32_t, AllocatorAligned,
                                           t1::ojph::NarrowShiftOJPHFilter>(
              src, block->resno, block->bandOrientation, block);
      }
    }
  }
  else
  {
    // Standard int32 path
    auto src = Buffer2d<T, AllocatorAligned>(srcData, false, cblk->width(), stride, cblk->height());
    if(!empty)
    {
      if(regionWindow)
      {
        if(block->roishift)
        {
          if(block->qmfbid == 1)
            src.template copyFrom<t1::ojph::RoiShiftOJPHFilter<T>>(
                src, t1::ojph::RoiShiftOJPHFilter<T>{block});
          else
            src.template copyFrom<t1::ojph::RoiScaleOJPHFilter<T>>(
                src, t1::ojph::RoiScaleOJPHFilter<T>{block});
        }
        else
        {
          if(block->qmfbid == 1)
            src.template copyFrom<t1::ojph::ShiftOJPHFilter<T>>(
                src, t1::ojph::ShiftOJPHFilter<T>{block});
          else
            src.template copyFrom<t1::ojph::ScaleOJPHFilter<T>>(
                src, t1::ojph::ScaleOJPHFilter<T>{block});
        }
      }
      else
      {
        src.setRect(blockBounds);
        if(block->roishift)
        {
          if(block->qmfbid == 1)
            postProcess<t1::ojph::RoiShiftOJPHFilter<T>>(src, block->resno, block->bandOrientation,
                                                         block);
          else
            postProcess<t1::ojph::RoiScaleOJPHFilter<T>>(src, block->resno, block->bandOrientation,
                                                         block);
        }
        else
        {
          if(block->qmfbid == 1)
            postProcess<t1::ojph::ShiftOJPHFilter<T>>(src, block->resno, block->bandOrientation,
                                                      block);
          else
            postProcess<t1::ojph::ScaleOJPHFilter<T>>(src, block->resno, block->bandOrientation,
                                                      block);
        }
      }
    }
    if(regionWindow)
      regionWindow->write(block->resno, blockBounds, empty ? nullptr : srcData, 1,
                          blockBounds.width());
  }
}
 
} // namespace grk