// Layer.h

#ifndef Layer_H
#define Layer_H

// Layers describe the geometry of the detector.  Each layer is
// composed of surfaces.  The composition may be direct or via other
// layers.
//
// The layer provides the methods propagate which propagate a track
// to the next of its constituent surfaces.  The propagate methods are
// passed a propagator which carries out the action and determines the
// direction.
//
// Propagation returns a list of layer tracks. A layer track is a
// kinematic track plus a layer status.  The layer status may also
// contain a miss and a cluster finder.  It is expected that each of
// the returned tracks will be updated with the miss and clusters
// and then propagated through the layer again until the status indicates
// the track has reached a layer exit.
//
// There are two methods of propagation: both are passed the track and
// the propagator but in the second the track is wrapped in the layer
// track.  The first is used when entering the layer and the second
// for all calls within the layer.
//
// Both of these propagate methods are implemented here.  Subclasses
// do not override these but must provide the method _propagate which is
// used by these.  Its interface is described below.
//
// If there are a lists of clusters associated layer, the method
// get_clusters may be used to access them.
//
//
// NOTICE for subclass developers:
//
// The major method that subclasses must implement is
// void _propagate(const LTrack& trl, const Propagator& prop,
//                 LTrackList& ltracks) const .
// The input is a layer track and a propagator and the output is a list
// of layer tracks.  The output layer tracks would typically be created
// by copying from the input layer track and then modifying it two
// components: the kinematic track and the layer status chain.
//
// The layer chain includes a list of layer status objects and two pointers
// to this list: one for the current layer postion and one for the
// status which contains the list of clusters and the miss.
//
// When a layer is nested (i.e. composed of other layers), the chain must
// be advanced to that layer before calling the propagate method of a
// sublayer.  The current status should be set to that same position when
// layer when returning from propagation.
//
// The cluster pointer is not set automatically.  The layer class
// contributing the status containing a cluster list or miss should
// call LTrack::set_cluster_status() to set this pointer.
//
// 30jun00 dla
// The propagate interfaces have been changed so that the user provides
// the list of LTrack's and the layer appends to that list.
//

#include "trfobj/TrfObject.h"
#include "trfbase/SurfacePtr.h"
#include "ptr/Ptr.h"
#include <cassert>
#include <vector>
#include "trfbase/Hit.h"
#include "LTrack.h"

namespace trf {

class Surface;
class Propagator;
class Cluster;
class Miss;
class Layer;

// output stream
std::ostream& operator<<(std::ostream& stream, const Layer& rhs);

class Layer : public TrfObject {

public:  // typedefs

  // Surface pointer and list.
  typedef std::vector<SurfacePtr>   SurfaceList;

public:  // static methods

  // Return the type name.
  static TypeName get_type_name() { return "Layer"; }

  // Return the creator.
  static ObjCreator get_creator();

  // Return the type.
  static Type get_static_type() { return get_creator(); }

private:  // methods implemented here

  // hide the copy constructor
  Layer(const Layer& rhs);

  // hide the assignment operator
  Layer& operator=(const Layer& rhs);

protected:  // methods

  // Subclasses call this method if they are passed an invalid
  // surface.
  void report_invalid_surface(SurfacePtr psrf) const;

public:  // methods implemented here

  // constructor
  Layer();

  // destructor
  virtual ~Layer();

  // Return the generic type of this class.
  // Subclasses must not override.
  Type get_generic_type() const { return get_static_type(); }

  // Propagate a track to the first surface in this layer.
  // This simply constructs a status and calls the virtual method.
  void propagate(const ETrack& tre, const Propagator& prop,
                 LTrackList& ltracks) const;

  // Propagate a track to the next surface in this layer.
  // The status is that from the previous surface in the layer.
  void propagate(const LTrack& trl, const Propagator& prop,
                 LTrackList& ltracks) const;

  // Return whether this layer or its descendants contains clusters.
  // Returns false if get_cluster_surfaces() returns an empty list.
  virtual bool has_clusters() const
    { return get_cluster_surfaces().size(); };

// friends

  // output stream
  friend std::ostream&
  operator<<(std::ostream& stream, const Layer& rhs);

private:  // methods to be implemented in subclasses

  // output stream
  virtual void ostr(std::ostream& stream) const =0;

  // Propagate a track to the next surface in this layer.
  // The list of succesful propagations is returned.
  // When layers are nested, this method in the parent will typically
  // invoke the same method for each of its children.
  virtual void _propagate(const LTrack& trl, const Propagator& prop,
                          LTrackList& ltracks) const =0;

public:  // methods to be implemented in subclasses

  // Return the list of active surfaces -- i.e. surfaces associated
  // with clusters.  These should include surfaces in sublayers.
  // Default method reports no surfaces.
  virtual SurfaceList get_cluster_surfaces() const;

  // Return all the clusters associated with the current layer
  // or its descendants.
  // Default here is to crash or return an error.
  virtual ClusterList get_clusters() const;

  // Return all the clusters associated with a particular surface
  // in this layer.
  // This method should call report_invalid_surface(SurfacePtr)
  // if it does not recognize the argument.
  virtual ClusterList get_clusters(SurfacePtr psrf) const;

  // Add a cluster to the layer.
  // Default here is to crash or return an error.
  virtual int add_cluster(const ClusterPtr& pclu);

  // Add a cluster to a particular surface in the layer.
  // Default here is to crash or return an error.
  virtual int add_cluster(const ClusterPtr& pclu, SurfacePtr psrf);

  // Drop all clusters from this layer.
  // Default here is to crash or return an error.
  virtual void drop_clusters();

};

}  // end namespace trf

#endif