mlPagedImage.h

Go to the documentation of this file.

/*************************************************************************************
**
** Copyright 2007, MeVis Medical Solutions AG
**
** The user may use this file in accordance with the license agreement provided with
** the Software or, alternatively, in accordance with the terms contained in a
** written agreement between the user and MeVis Medical Solutions AG.
**
** For further information use the contact form at https://www.mevislab.de/contact
**
**************************************************************************************/
 
#ifndef ML_PAGED_IMAGE_H
#define ML_PAGED_IMAGE_H
 
 
//ML-includes
#include "mlInitSystemML.h"
#include "mlMedicalImageProperties.h"
#include "mlMemoryImage.h"
 
#include "mlInputSubImageProperties.h"
#include "mlModuleInterfaces.h"
 
#include <mlMemoryBlockHandle.h>
#include <mlWeakMemoryBlockHandle.h>
 
#include <unordered_map>
#include <vector>
 
ML_START_NAMESPACE
 
class PagedImageCurrentlyUsedMemoryTracker;
class Module;
class SubImage;
class PageRequest;
class TileRequest;
 
#if ML_DEPRECATED_SINCE(3,5,0)
class BaseOp;
#endif
 
 
//------------------------------------------------------------------------------
//------------------------------------------------------------------------------
class ML_UNIX_ONLY_EXPORT(MLEXPORT) PagedImage: public MedicalImageProperties
{
  struct PageEntry
  {
    MLWeakMemoryBlockHandle page;
    PageRequest* pendingRequest{};
  };
 
  struct ExtendedPageEntry;
 
public:
  enum ThreadSupport {
    NO_THREAD_SUPPORT = 0, 
    MULTITHREADED     = 1, 
    IO_THREAD         = 4, 
    USE_MODULE_THREAD_SUPPORT = -1  
  };
 
  friend class Host;
 
  // needed for testing protected API:
  ML_FRIEND_TEST(PagedImageDeprecationTest, NewAPI);
  ML_FRIEND_TEST(PagedImageDeprecationTest, DeprecatedAPI);
  ML_FRIEND_TEST(TypedHandlersTest, SetupAndVerifyProperties);
 
  //------------------------------------------------------
  //------------------------------------------------------
 
  MLEXPORT PagedImage(Module* module=nullptr, MLint outputIndex=-1);
 
  MLEXPORT ~PagedImage() override;
 
  inline CalculateOutputImageHandler* getCalculateOutputImageHandler() const { return _calculateOutputImageHandler; }
 
  MLEXPORT void setExternalCalculateOutputImageHandler(CalculateOutputImageHandler* handler);
 
  inline bool hasExternalCalculateOutputImageHandler() const { return _isExternalCalculateOutputImageHandler; }
 
  MLEXPORT void setCalculateOutputImageHandler(CalculateOutputImageHandler* handler);
 
  MLEXPORT void setCalculateOutputImagePropertiesCB(CalculateOutputImagePropertiesCB* callback, void* userData);
 
  inline MLuint32 getID() { return _id; }
 
  inline void updateID() { _id = getUniqueId(); }
 
  //-------------------------------------------------------------------
  //-------------------------------------------------------------------
  inline bool isValid() const { return _isValid;    }
 
  inline void setValid(bool flag = true)      { _isValid=flag;      }
 
  inline void setInvalid()     { _isValid=false;     }
 
  MLEXPORT void setUpdateOfImagePropertiesNeeded(bool flag);
 
  MLEXPORT bool updateOfImagePropertiesNeeded() const { return _updateOfImagePropertiesNeeded; }
 
  [[nodiscard]]
  MLEXPORT MLErrorCode updateImageProperties();
 
 
  //------------------------------------------------------
  //------------------------------------------------------
 
  MLEXPORT virtual void setImageExtent(const ImageVector& extent);
 
  inline void           setImageExtent(MLint x, MLint y, MLint z = 1, MLint c = 1, MLint t = 1, MLint u = 1) {
    setImageExtent(ImageVector(x,y,z,c,t,u));
  }
 
  inline void           setImageExtent(const SubImageBox &box) { setImageExtent(box.getExtent()); }
 
  MLEXPORT virtual void setImageProperties(const PagedImage& imageProperties);
 
  MLEXPORT void         setPageExtent(const ImageVector& pageExtent);
 
  inline void           setClampPagesToImageExtent(bool flag = true) { _clampPagesToImageExtent = flag; }
 
  inline bool           getClampPagesToImageExtent() const { return _clampPagesToImageExtent; }
 
  inline void           setPageExtent(MLint x, MLint y, MLint z = 1, MLint c = 1, MLint t = 1, MLint u = 1) {
    setPageExtent(ImageVector(x,y,z,c,t,u));
  }
 
  MLEXPORT void         setDataType(MLDataType dataType) override;
 
  MLEXPORT void         setMinVoxelValue(MLdouble minval);
 
  MLEXPORT void         setMaxVoxelValue(MLdouble maxval);
 
  MLEXPORT void         setPage(MLint pageID, const MLMemoryBlockHandle& page);
 
  MLEXPORT void         removePage(MLint pageID);
 
  MLEXPORT void         deletePageEntryFromDeletionCallback(ExtendedPageEntry* entry);
 
  MLEXPORT void         clearPageList();
 
  MLEXPORT void         clearPageListAndMemoryImage();
 
 
 
  //------------------------------------------------------
  //------------------------------------------------------
  MLEXPORT virtual void setStateInfo(const std::string& info, MLErrorCode errorCode);
 
  MLEXPORT virtual void setStateInfoErrorCode(MLErrorCode errorCode);
 
  MLEXPORT virtual const std::string& getStateInfoString() const;
 
  MLEXPORT virtual MLErrorCode getStateInfoErrorCode() const;
 
  //---------------------------------------------------------------------------
  //---------------------------------------------------------------------------
 
  inline void setBypassIndex(MLint index) { _bypassIndex = index; }
 
  inline MLint getBypassIndex() const     { return _bypassIndex;  }
 
 
  //------------------------------------------------------
  //------------------------------------------------------
 
  inline Module*            getModule() const              { return _module; }
 
  MLEXPORT const PagedImage*  getInputImage(int inputIndex) const;
 
  inline MLint              getOutputIndex() const            { return _outIndex; }
 
  inline ImageVector        getPageSetExtent() const  { return _pageSetExt; }
 
  inline ImageVector        getPageStride() const     { return _pageStride; }
 
  inline ImageVector        getPageExtent() const     { return _pageExt; }
 
  inline MLint              getPageID(const ImageVector& voxelPosition) const { return (voxelPosition/_pageExt).dot(_pageStride); }
 
  inline MemoryImage&         getMemoryImage()       { return _memoryImg; }
  inline const MemoryImage&   getMemoryImage() const { return _memoryImg; }
 
  MLEXPORT void setThreadSupport(ThreadSupport support) { _threadSupport = support; }
 
  MLEXPORT ThreadSupport getThreadSupport() const;
 
  MLEXPORT MLMemoryBlockHandle getPage(MLint pageID) const;
 
  MLEXPORT MLMemoryBlockHandle getPageOrCreatePageRequestOrAddToPendingRequest(MLint& pageID, TileRequest* tileRequest, PageRequest** newPageRequest);
 
  MLEXPORT void clearPendingPageRequest(MLint pageID);
 
  MLEXPORT PagedImage&   getBypassSourceImage();
 
  MLEXPORT SubImageBox   getPageBox(MLint pageID) const;
 
  MLEXPORT void        getPageIDs(std::vector <MLint>& pageIDs, const SubImageBox& subImageBox) const;
 
  MLEXPORT static void getPageIDs(std::vector<MLint>& pageIDs,
                                  const SubImageBox&    subImageBox,
                                  const ImageVector&  imageExtent,
                                  const ImageVector&  pageExtent);
 
  MLEXPORT std::size_t      getCachedPagesSizeInBytes() const;
 
  MLEXPORT MLint       getNumPages() const { return _pageSetSize; }
 
 
 
  //---------------------------------------------------------------------------
  //---------------------------------------------------------------------------
 
  inline void setInPlaceIndex(MLint inputIndex) { _inPlaceIndex = inputIndex; }
 
  inline MLint getInPlaceIndex() const    { return _inPlaceIndex;  }
 
 
  //------------------------------------------------------
  //------------------------------------------------------
 
  MLEXPORT void setInputSubImageDataType(int inputIndex, MLDataType dataType);
 
  MLEXPORT void setInputSubImageIsReadOnly(int inputIndex, bool readOnly);
 
  MLEXPORT void setInputSubImagesAreReadOnly(bool readOnly = true);
 
  MLEXPORT void setInputSubImageUseMemoryImage(int inputIndex, bool useMemoryImage);
 
  MLEXPORT void setInputSubImageScaleShift(int inputIndex, const ScaleShiftData& scaleShift);
 
  MLEXPORT const InputSubImageProperties &getInputSubImageProperties(int inputIndex) const;
 
  MLEXPORT MLDataType getInputSubImageDataType(int inputIndex) const;
 
  MLEXPORT bool getInputSubImageIsReadOnly(int inputIndex) const;
 
 
  //------------------------------------------------------
  //------------------------------------------------------
 
  //---------------------------------------------------------------------------------
  //---------------------------------------------------------------------------------
  MLEXPORT void copyPages(const std::vector<MLint>& pageIDs,
                          SubImage*                   subImage,
                          const ScaleShiftData&     scaleShiftData=ScaleShiftData()) const;
 
 
  //-------------------------------------------------------------------
  //-------------------------------------------------------------------
  [[nodiscard]]
  MLEXPORT MLErrorCode getTile(SubImageBox              location,
                               MLDataType             dataType,
                               void**                 data,
                               const ScaleShiftData&  scaleShiftData=ScaleShiftData(),
                               MLRequestProgressCB*   progressCallback = nullptr,
                               void*                  progressCallbackUserData = nullptr);
 
  [[nodiscard]]
  MLEXPORT MLErrorCode getTile(SubImage& subImage, const ScaleShiftData& scaleShiftData=ScaleShiftData(),
                               MLRequestProgressCB* progressCallback = nullptr,
                               void*                progressCallbackUserData = nullptr);
 
  MLEXPORT void freeTile(void* data);
 
  MLEXPORT MLdouble getInterpolatedValue(const Vector3& pos, MLint c = 0, MLint t = 0, MLint u = 0, MLdouble outsideFillValue = 0);
 
 
  MLEXPORT MLMetaProfilePtr& getMetaProfile() const;
 
  MLEXPORT static void setPageCountLimitToUsePageEntryMap(MLuint32 limit) { _pageCountLimitToUsePageEntryMap = limit; }
 
  MLEXPORT static MLuint32 getPageCountLimitToUsePageEntryMap() { return _pageCountLimitToUsePageEntryMap; }
 
protected:
  MLEXPORT void calculateImageProperties();
 
  MLEXPORT void initializeInputSubImageProperties(MLint numInputs);
 
  MLEXPORT void validateInputSubImagePropertiesAfterCalculateOutputImageProperties();
 
private:
  static MLuint32 getUniqueId();
 
  MLEXPORT bool arePropertiesLocked() const { return _propertiesLocked; }
 
  MLEXPORT bool setPropertiesLocked(bool locked);
 
  inline bool _checkPropertyWriteAccess(const char* methodName) {
    if (_propertiesLocked) {
      _showInvalidPropertyWriteAccessError(methodName);
    }
    return !_propertiesLocked;
  }
 
  void _showInvalidPropertyWriteAccessError(const char* methodName);
 
  PagedImage(const PagedImage&) = delete;
  PagedImage& operator=(const PagedImage&) = delete;
 
 
  //------------------------------------------------------
  //------------------------------------------------------
  void _updateAll();
 
 
  void _allocatePageList();
 
 
  void static deleteMemoryBlockCallback(void* data, size_t size, void* userData);
 
  /*
   * Returns true, of the registration was successfully otherwise false
   */
  static bool registerDeletionCallback(const ExtendedPageEntry* entry);
 
  /*
   * This returns true, if the ownership of the entry stays within this class
   */
  static bool deregisterDeletionCallback(const ExtendedPageEntry* entry);
 
  static ExtendedPageEntry* deletePageEntryFromMapUnsafe(std::unordered_map<MLint, ExtendedPageEntry *> &pageEntryMap,
                                           MLint pageId);
 
  //------------------------------------------------------
  //------------------------------------------------------
 
  Module* _module;
 
  CalculateOutputImageHandler* _calculateOutputImageHandler;
 
  CalculateOutputImagePropertiesCB* _calculateOutputImageProperties;
  void*                             _calculateOutputImagePropertiesUserData;
 
  bool _isExternalCalculateOutputImageHandler;
 
  MLint            _outIndex;
 
  ImageVector           _pageExt;
 
  ImageVector           _pageStride;
 
  ImageVector           _pageSetExt;
 
  MLint                 _pageSetSize;
 
  std::vector<PageEntry>  _pageList;
 
  std::unordered_map<MLint, ExtendedPageEntry*> _pageEntryMap;
 
  mutable Mutex _pageAccessMutex;
 
  bool _pageHandlesAreStoredInList;
 
  MLint            _inPlaceIndex;
 
  MLint            _bypassIndex;
 
  bool             _updateOfImagePropertiesNeeded;
 
  bool             _isValid;
 
  bool             _propertiesLocked;
 
  bool             _clampPagesToImageExtent;
 
  MemoryImage      _memoryImg;
 
  std::string      _stateInfoString;
 
  MLErrorCode      _stateInfoErrorCode;
 
  MLuint32         _id;
 
  std::vector<InputSubImageProperties> _inSubImageProps;
 
  ThreadSupport    _threadSupport;
 
  mutable PagedImageCurrentlyUsedMemoryTracker* _currentlyUsedPageMemoryTracker;
 
  mutable MLMetaProfilePtr _metaProfilePtr;
 
  static MLuint32 _staticUniqueId;
 
  static MLuint32 _pageCountLimitToUsePageEntryMap;
 
private:
  static const char* const _pageAllocationMemoryProfileKey;
  static const char* const _pageCacheHitsCountProfileKey;
  static const char* const _pageCacheMissesCountProfileKey;
 
#if ML_DEPRECATED_SINCE(3,5,0)
 
 
public:
  // \deprecated
  // Use getOutputIndex() instead.
  inline ML_DEPRECATED MLint getOutIndex() const { return getOutputIndex(); }
 
  // \deprecated
  // Use isValid() instead.
  inline ML_DEPRECATED bool isUpToDate() const { return isValid();    }
 
  // \deprecated
  // Use setValid() instead.
  inline ML_DEPRECATED void setUpToDate()      { setValid(); }
 
  // \deprecated
  // Use setInvalid() instead.
  inline ML_DEPRECATED void setOutOfDate()     { setInvalid();     }
 
  MLEXPORT bool isGlobalDummyImage();
 
  inline ML_DEPRECATED void setImgExt(const ImageVector &ext) { setImageExtent(ext); }
  inline ML_DEPRECATED void setImgExt(const SubImageBox &box) { setImageExtent(box); }
  inline ML_DEPRECATED void clearPageListAndMemoryImg() { clearPageListAndMemoryImage(); }
  MLEXPORT ML_DEPRECATED BaseOp*  getBaseOp() const;
  inline ML_DEPRECATED void setImgProps(const PagedImage &imgProps) { setImageProperties(imgProps); }
  inline ML_DEPRECATED void setPageExt(const ImageVector &pageExt) { setPageExtent(pageExt); }
  inline ML_DEPRECATED const PagedImage* getInImg(int index) const { return getInputImage(index); }
  inline ML_DEPRECATED ImageVector getPageSetExt() const { return getPageSetExtent(); }
  inline ML_DEPRECATED ImageVector getPageExt() const { return getPageExtent(); }
  inline ML_DEPRECATED MemoryImage& getMemoryImg() { return getMemoryImage(); }
  inline ML_DEPRECATED const MemoryImage&  getMemoryImg() const { return getMemoryImage(); }
  inline ML_DEPRECATED size_t getPageMemorySize() const { return getCachedPagesSizeInBytes(); }
  inline ML_DEPRECATED void setInSubImageDataType(int inputIndex, MLDataType datatype) { setInputSubImageDataType(inputIndex,datatype); }
  inline ML_DEPRECATED void setInSubImageIsReadOnly(int inputIndex, bool readOnly) { setInputSubImageIsReadOnly(inputIndex, readOnly); }
  inline ML_DEPRECATED void setInSubImageUseMemoryImage(int inputIndex, bool useMemImg) { setInputSubImageUseMemoryImage(inputIndex, useMemImg); }
  inline ML_DEPRECATED void setInSubImageScaleShift(int inputIndex, const ScaleShiftData& scaleShift) { setInputSubImageScaleShift(inputIndex, scaleShift); }
  inline ML_DEPRECATED const InputSubImageProperties& getInSubImageProps(int inputIndex) const { return getInputSubImageProperties(inputIndex); }
  inline ML_DEPRECATED MLDataType getInSubImageDataType(int inputIndex) const { return getInputSubImageDataType(inputIndex); }
  inline ML_DEPRECATED bool getInSubImageIsReadOnly(int inputIndex) const { return getInputSubImageIsReadOnly(inputIndex); }
 
#endif
 
};
 
#if ML_DEPRECATED_SINCE(3,5,0)
ML_DEPRECATED typedef PagedImage PagedImg;
#endif
 
 
ML_END_NAMESPACE
 
// Stream output for std::ostream
namespace std {
 
  MLEXPORT std::ostream& operator<<(std::ostream& s, const ML_NAMESPACE::PagedImage &pi);
 
}
 
#endif //of __mlPagedImage_H