// Surface.h

#ifndef Surface_H
#define Surface_H

// TRF++ base class to describe a surface.
//
// There are two conceptual levels of concrete surfaces:
//  1. Pure surfaces are unbounded and are used to specify the set
//     of track parameters used in VTrack.  They derive directly
//     from Surface.  Typically these are named SurfXXX.
//  2. Bounded surfaces are derived from pure surfaces.
//     Typically these are named BSurfXXX.
//
// Typically the first two track parameters specify the position on the
// surface, the next two the direction of the track and the last is
// q/p where q is the charge (in natural units where the electron is -1)
// and p is the total momentum in GeV/c.  Note that the radius of
// curvature (in cm) is then Rc = cos(tht) / [ 0.003 * (q/p) * B ]
// where B is the magnetic field in Tesla and tht is the angle between the
// field and the direction.  Also 0.003 is actually 0.0029979....
//
// This is an abstract class.  Classes VTrack and Hit maintain pointers
// of this type.
//

#include <iosfwd>
#include "trfobj/TrfObject.h"
#include "TrackSurfaceDirection.h"

class SpacePoint;
class SpacePointVector;
class SpacePath;

namespace trf {

class CrossStat;
class TrackVector;
class Surface;
class VTrack;
class ETrack;

// Output stream operator.
std::ostream& operator<<(std::ostream& stream, const Surface& srf);

class Surface : public TrfObject {

// Statics  ************************************************************

public:

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

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

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

// Methods and friends implemented here.  *****************************

public:

  // constructor
  Surface();

  // destructor
  virtual ~Surface();

  // Return the full type.
  // This implementation returns the pure type ==>
  // Pure surfaces need not override.
  // Bound surfaces should override.
  Type get_type() const;

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

  // Return whether this surface is pure.
  bool is_pure( ) const { return get_type() == get_pure_type(); };

  // Return true if two surfaces are exactly the same 
  // including bounds.
  bool bound_equal(const Surface& srf) const;

  // Return true if two surfaces have the same pure surface.
  bool pure_equal(const Surface& srf) const;

  // Ordering operator.  Returns true if this surface comes before the
  // argument surface.  Comparison is based on the pure parameters only.
  // As usual exactly one of a<b, b<a and a==b is true and all comparisons
  // are transitive.
  bool pure_less_than(const Surface& srf) const;

  // Return q/p in 1/GeV/c.  This is proportioanl to curvature.
  // Override for non-standard fith track parameter.
  virtual double qoverp(const TrackVector& vec) const;

  // Return the direction consistent with the specified track vector.
  // The default defined here returns TSD_UNDEFINED.
  // Subclasses for which the track vector does specify the direction
  // should override this method.
  // If the vector is ambiguous, then VTrack carries an attribute
  // which is used to specify the direction.
  virtual TrackSurfaceDirection 
    get_direction(const TrackVector& vec) const;

  // Output stream operator.
  friend std::ostream&
  operator<<(std::ostream& stream, const Surface& srf);

// Methods to implement in all surfaces.  *****************************

public:

  // Write a brief description of the surface to an output stream.
  virtual void ostr(std::ostream& stream) const = 0;

// Methods to implement only in pure surfaces.  ***********************

private:

  // Return true if two surfaces have the same pure surface.
  // Argument may be safely downcast.
  virtual bool safe_pure_equal(const Surface& srf) const = 0;

  // Return true if this surface and the argument are in order.
  // See pure_less_than() for more information.
  // Argument may be safely downcast.
  virtual bool safe_pure_less_than(const Surface& srf) const = 0;

public:

  // Return the pure type.
  virtual Type get_pure_type() const = 0;

  // Return a new surface corresponding to the underlying pure surface.
  // Caller is responsible for deleting the returned surface.
  virtual Surface* new_pure_surface() const = 0;

  // Return the crossing status for a track without error.
  // Subclasses should override the return type with their own
  // crossing status.
  virtual CrossStat pure_status(const VTrack& trv) const = 0;

  // Return the surface parameter with specified index (0, 1, 2, 3, 4).
  // Default is to return parameter 0.
  virtual double get_parameter(int i) const =0;

  // Return the difference between two vectors on the surface.
  virtual TrackVector vec_diff(const TrackVector& vec1, 
                               const TrackVector& vec2) const = 0;

  // Return the position of a track vector.
  virtual SpacePoint space_point(const TrackVector& vec) const = 0;

  // Return the position and direction of a track vector.
  virtual SpacePath
  space_vector(const TrackVector& vec,
               TrackSurfaceDirection dir =TSD_UNDEFINED) const = 0;


// Methods to implement only in bounded surfaces.  *******************

// The default implementations for these methods are only appropriate
// for pure surfaces.  Bounded surfaces must override.  This is checked
// with an assertion.

protected:

  // Return true if two surfaces are exactly the same 
  // including bounds.  Argument may be safely downcast.
  // This method should be implemented by all bounded surfaces.
  virtual bool safe_bound_equal(const Surface& srf) const;

public:

  // Return a new surface of the full type (clone).
  // The default implentation is appropriate only for a pure surface.
  virtual Surface* new_surface() const;

  // Return the crossing status for a track without or with error.
  // Without error should produce the same result as with error
  // with zero errors.
  // 
  virtual CrossStat status(const VTrack& tre) const;
  virtual CrossStat status(const ETrack& tre) const;

};

}  // end namespace trf

// External functions.

// Equality operator.
// This compares the full surface types.
bool operator==(const trf::Surface& srf1, const trf::Surface& srf2);

// Inequality operator.
bool operator!=(const trf::Surface& srf1, const trf::Surface& srf2);

#endif