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;
 
 
//------------------------------------------------------------------------------
//------------------------------------------------------------------------------
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 \c true if the registration was successfully; otherwise, it returns \c false.
   */
  static bool registerDeletionCallback(const ExtendedPageEntry* entry);
 
  /*
   * This returns \c 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;
};
 
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