IFilter.hpp

#ifndef DM_IFILTER_HPP_INCLUDED
#define DM_IFILTER_HPP_INCLUDED

#ifdef _MSC_VER
  #pragma once
#endif

#include "DM/config.hpp"
#include "DM/Handle.hpp"
#include "DM/ObjectBase.hpp"
#include "DM/IGeometry.hpp"
#include "DM/IBox.hpp"
#include "DM/IAddInfoStatistics.hpp"
#include "DM/IFilterStats.hpp"
#include "DM/AutoLink.hpp" //enable autolink

#include <vector>
#include <string>

DM_NAMESPACE_BEGIN

class DM_API IFilter : public ObjectBase
{
public:
  /// Choose the level of write access:
  struct WriteAccess
  {
    enum Type
    {
      none,                                  ///< support no write access at all
      coordinates,                           ///< support write access to coordinates
      attributes     = coordinates << 1,     ///< support write access to attributes
      delayedResults = attributes << 1,      ///< support filters that provide delayed results; use IFilter::submit(.) / IFilter::fetch() instead of IFilter::validate(.)
      full           = (delayedResults<<1)-1 ///< full write access
    };
  };
  
  static IFilter* New();
  // Returns nullptr if stringRepresentation contains white space only.
  static IFilter* New( const char *stringRepresentation, WriteAccess::Type writeAccess = WriteAccess::none );

  virtual IFilter* clone() const = 0;

  // Only applicable for filters (filter trees) that don't use caching. Otherwise: throw
  virtual bool validate( IGeometry &geom ) const = 0;
  virtual bool validate( const IGeometry &geom ) const = 0;

  // Also applicable for filters (filter trees) that use caching
  virtual void submit( GeometryHandle geo, const void * userData = 0 ) const = 0;

  // Indicate that no more data will be submitted. The rest of the already submitted geometries will be returned by subsequent calls to fetch()
  // Do not call submit() after flush() has been called.
  virtual void flush() const = 0;

  struct IResult : public ObjectBase
  {
    // Is true, if *this considers filtered as valid. Meaningless, if filtered is NULL
    virtual bool valid() const = 0;
    // The filtered object (changed from original submitted object, if modifiesObjects()==true); if NULL, then there is no result yet, or no result left
    virtual GeometryHandle filtered() const = 0;
    // If provideOrigObjects(true), then this is the original, unchanged object as submitted; otherwise orig==filtered
    virtual GeometryHandle orig() const = 0;
    // Arbitrary data set by users, kept together untouched with submitted geometries.
    virtual const void * userData() const = 0;
  };
  typedef Handle< IResult > ResultHandle;
  // return the next available result.
  // Performance note: call fetch() alternately with submit(), to keep the (eventual) internal cache size small
  // Note that a single submission yields an arbitrary number of results, including zero.
  // Thus, call submit once, and call fetch repeatedly until it returns an empty pointer in Result::filtered
  virtual ResultHandle fetch() const = 0;
  
  // return false if data inside box having statistics of addInfoStats will surely not pass through (-> e.g. skip this ODM tile)
  virtual bool mayBeValid( const IBox &box, const IAddInfoStatistics &addInfoStats ) const = 0;

  struct TriBool { enum Type { indeterminate = -1, false_, true_ };  };
  // return true_  if surely all         data within box having addInfoStats would pass through the filter.
  // return false_ if surely none of the data within box having addInfoStats would pass through the filter.
  // return indeterminate_ otherwise.
  virtual TriBool::Type validateRange( const IBox &box, const IAddInfoStatistics &addInfoStats ) const = 0;

  // Provide the original, unchanged geometries and attributes in Result::orig and FilterStats::accumulate
  virtual void provideOrigObjects( bool val = true ) = 0;

  /// accumulate statistical information about the results of filtering
  virtual void stats( FilterStatsHandle obj ) = 0;
  virtual FilterStatsHandle stats() = 0;

  virtual std::vector<std::string> accessedAttributeNames() const = 0;
  virtual void print(std::ostream&) const = 0;
};

typedef Handle< IFilter > FilterHandle;

DM_API FilterHandle operator||( const IFilter&, const IFilter& );
DM_API FilterHandle operator&&( const IFilter&, const IFilter& );

DM_API IFilter::WriteAccess::Type operator| ( const IFilter::WriteAccess::Type &left, const IFilter::WriteAccess::Type &right );

DM_NAMESPACE_END

#endif //DM_IFILTER_HPP_INCLUDED