MeVis/Foundation/Sources/ML/include/mlPagedImage.h

Go to the documentation of this file.

// **InsertLicense** code
//------------------------------------------------------------------------------
//------------------------------------------------------------------------------
#ifndef __mlPagedImage_H
#define __mlPagedImage_H

//ML-includes
#ifndef __mlInitSystemML_H
#include "mlInitSystemML.h"
#endif
#ifndef __mlMedicalImageProperties_H
#include "mlMedicalImageProperties.h"
#endif
#ifndef __mlMemoryImage_H
#include "mlMemoryImage.h"
#endif

#include "mlInputSubImageProperties.h"
#include "mlModuleInterfaces.h"
#include "mlRangeCasts.h"

#include <mlMemoryBlockHandle.h>
#include <mlMetaProfilePtr.h>

#include "mlSystemWarningsDisable.h"
#include <boost/unordered_map.hpp>
#include "mlSystemWarningsRestore.h"

ML_START_NAMESPACE

class PagedImageCurrentlyUsedMemoryTracker;
class Module;
class SubImage;
class PageRequest;
class TileRequest;
struct PagedImagePageEntry;
struct PagedImageExtendedPageEntry;
#ifdef ML_DEPRECATED
class BaseOp;
#endif



//------------------------------------------------------------------------------
//------------------------------------------------------------------------------
class ML_UNIX_ONLY_EXPORT(MLEXPORT) PagedImage: public MedicalImageProperties
{

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);

  //------------------------------------------------------

  //------------------------------------------------------

  MLEXPORT PagedImage(Module* module=NULL, MLint outputIndex=-1);

  MLEXPORT virtual ~PagedImage();

  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; }

  MLEXPORT MLErrorCode updateImageProperties() ML_RETURN_VALUE_SHOULD_BE_USED;


  //------------------------------------------------------

  //------------------------------------------------------

  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           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         setPage(MLint pageID, const MLMemoryBlockHandle& page);

  MLEXPORT void         removePage(MLint pageID);

  MLEXPORT void         deletePageEntryFromDeletionCallback(PagedImageExtendedPageEntry* 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 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);

  inline const InputSubImageProperties& getInputSubImageProperties(int inputIndex) const { return _inSubImageProps[mlrange_cast<size_t>(inputIndex)]; }

  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;


  //-------------------------------------------------------------------

  //-------------------------------------------------------------------
  MLEXPORT MLErrorCode getTile(SubImageBox              location,
                               MLDataType             dataType,
                               void**                 data,
                               const ScaleShiftData&  scaleShiftData=ScaleShiftData()) ML_RETURN_VALUE_SHOULD_BE_USED;

  MLEXPORT MLErrorCode getTile(SubImage& subImage, const ScaleShiftData& scaleShiftData=ScaleShiftData()) ML_RETURN_VALUE_SHOULD_BE_USED;

  MLEXPORT void freeTile(void* data);

  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();

  //------------------------------------------------------

  //------------------------------------------------------
  PagedImage(const PagedImage&);

  PagedImage& operator=(const PagedImage&);


  //------------------------------------------------------

  //------------------------------------------------------
  void _updateAll();

  void _deletePageList();

  void _allocatePageList();


  //------------------------------------------------------

  //------------------------------------------------------

  Module* _module;

  CalculateOutputImageHandler* _calculateOutputImageHandler;

  CalculateOutputImagePropertiesCB* _calculateOutputImageProperties;
  void*                             _calculateOutputImagePropertiesUserData;

  bool _isExternalCalculateOutputImageHandler;

  MLint            _outIndex;

  ImageVector           _pageExt;

  ImageVector           _pageStride;

  ImageVector           _pageSetExt;

  MLint                 _pageSetSize;

  PagedImagePageEntry*  _pageList;

  boost::unordered_map<MLint, PagedImageExtendedPageEntry*> _pageEntryMap;

  mutable Mutex _pageAccessMutex;

  bool _pageHandlesAreStoredInList;

  MLint            _inPlaceIndex;

  MLint            _bypassIndex;

  bool             _updateOfImagePropertiesNeeded;

  bool             _isValid;

  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;

#ifdef ML_DEPRECATED



public:
  static const char* const pageAllocationMemoryProfileKey;
  static const char* const pageCacheHitsCountProfileKey;
  static const char* const pageCacheMissesCountProfileKey;


  // \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 // ML_DEPRECATED

};

#ifdef ML_DEPRECATED




ML_DEPRECATED typedef PagedImage PagedImg;
#endif // ML_DEPRECATED


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