/////////////////////////////////////////////////////////////////////////////
// EuProcessor.h
//
// Copyright (C) 2003-2010 Euphonix, Inc.
// This source code is licensed under the EuCon SDK License Agreement.
// All rights reserved.
//
// Date:        Tuesday, January 27, 2004
// Author:      PCAMPBELL
// Description: Base class for EuCon processor units
/////////////////////////////////////////////////////////////////////////////

#if !defined(__EUPHONIX_EUPROCESSOR_H__)
#define __EUPHONIX_EUPROCESSOR_H__

#include "EuDefinitions.h"
#include "EuCommon.h"

#include <vector>

class EuControl;
class EuPrimitiveControl;
class EuSurfaceBrowser;
class EuProcessorBrowser;
class EuNode;

class EUAPI_CLASS  EuProcessor : public EuCommon
{
public:

    // constructor and initialization methods
    EUAPI_FUNC EuProcessor();
    virtual EUAPI_FUNC ~EuProcessor();

    // These methods are used in creating a new EuProcessor-derived class

    EUAPI_FUNC tERR SetLabel(tEuString& i4Char, tEuString& i8Char, tEuString& iLong);

    EUAPI_FUNC tERR AddControl(EuControl& iControl);
    EUAPI_FUNC tERR RemoveControl(EuControl& iControl);
    EUAPI_FUNC tERR GetContainedControls(std::vector<EuControl*>& oControls) const;

    EUAPI_FUNC tERR AddProcessor(EuProcessor& iProcessor);
    EUAPI_FUNC tERR GetContainedProcessors (std::vector<EuProcessor*>& oProcessors) const;

    // *oppParentProcessor will be null if no parent; if so, then call GetParent( EuNode ), below
    EUAPI_FUNC tERR GetParent( EuProcessor** oppParentProcessor ) const;
    EUAPI_FUNC tERR GetParent( EuNode** oppParentEuNode ) const;  // *oppParentEuNode will be null if parent not an EuNode

    ////////////////////////////////////////////////////////////////////////////////////////////////
    //
    //  To avoid a race condition, two callbacks are provided: OnConfirmValueCallback() and OnCallback().
    //
    //  The first callback (OnConfirmValueCallback) provides the model a way to confirm or change the
    //  requested index (ioRequestedNewIndex); deciding if this is necessary is up to the modeler.
    //
    //  Confirming or altering the requested index is the only operation that should be performed in
    //  OnConfirmValueCallback(); otherwise a race condition can occur, as the control is still set to
    //  the old index, and is waiting for OnConfirmValueCallback to return with the confirmed new value.
    //
    //  OnConfirmValueCallback() is not called by default.  To enable OnConfirmValueCallback, invoke
    //  MakeConfirmationCallback( bool ) in each Primitive Control you wish to enable it for (see
    //  EuPrimitiveControl.h):
    //
    //      MakeConfirmationCallback( true );  // default is false:  OnConfirmValueCallback() is not called.
    //
    //  (Note that OnConfirmValueCallback() must be overloaded by the derived EuProcessor class whether it
    //  is to be called or not.)
    //
    //  Also, if the modeler decides no confirmation is needed for certain controls, the processor can
    //  simply return from OnConfirmValueCallback() without handling all cases, and ioRequestedNewIndex
    //  will be used unchanged as the new index for any unhandled cases.
    //
    //  When OnConfirmValueCallback() returns, the internal EuProcessor code will update the control to
    //  the new index (ioRequestedNewIndex).  It will then immediately make the second callback (OnCallback),
    //  where the real work is done by the processor.
    //
    ////////////////////////////////////////////////////////////////////////////////////////////////



    /////////////////////////////////////////////////////////////////////////////////////////////////
    //
    // This method must be overloaded in the derived class.
    //
    // If desired, modify the new value (ioRequestedNewIndex) requested by the surface.
    //
    virtual EUAPI_FUNC void OnConfirmValueCallback( NEuCon::uint32         iEventFlags,
                                                    NEuCon::uint32         iControlId,
                                                    NEuCon::uint32         iArrayMemberControlId,
                                                    NEuCon::uint32         iPrimitiveId,
                                                    EuPrimitiveControl*    iAffectedPrimitive,
                                                    NEuCon::uint16&        ioRequestedNewValueIndex  );



    /////////////////////////////////////////////////////////////////////////////////////////////////////
    //
    // This method must be overloaded in the derived class
    //
    //  OnPrimitiveCallback
    //
    //    All primitive-related events:  Events relating to Primitive controls
    //
    //    Examples:  Attribute changes, freeze/thaw notifications, real-time state (index) changes
    //
    //    The model should update its state, as well as the state of the rest of the processor-host
    //    program, within this callback.
    //
    virtual EUAPI_FUNC void OnPrimitiveCallback( tEVT                  iEventType,
                                                 NEuCon::uint32        iEventFlags,
                                                 NEuCon::uint32        iControlId,
                                                 NEuCon::uint32        iArrayMemberControlId,
                                                 NEuCon::uint32        iPrimitiveId,
                                                 EuPrimitiveControl*   iAffectedPrimitive,
                                                 NEuCon::uint16        iNewValueIndex,
                                                 void*                 iCallbackEventData = NULL  );


    /////////////////////////////////////////////////////////////////////////////////////////////////////
    //
    // This method must be overloaded in the derived class
    //
    //  OnControlCallback
    //
    //    All control-related events:  Events relating to control or control-array members
    //
    //    Examples:  Attribute changes, freeze/thaw notifications,
    //               Add/Remove array members, etc.
    //
    //    Note:  Use iEventFlags to determine if the event involves a control, or a member
    //           of a control array.  See kCONTROL_FLAG_xxx in EuDefinitions.h
    //
    //           iArrayMemberControlId is only used when (iEventFlags & kCONTROL_FLAG__MEMBER_EVENT == true)
    //
    virtual EUAPI_FUNC void OnControlCallback( tEVT            iEventType,
                                               NEuCon::uint32  iEventFlags,
                                               NEuCon::uint32  iControlId,
                                               NEuCon::uint32  iArrayMemberControlId,
                                               EuControl*      iAffectedControl,
                                               void*           iCallbackEventData = NULL  );


    /////////////////////////////////////////////////////////////////////////////////////////////////////
    //
    // This method must be overloaded in the derived class
    //
    //  OnProcessorCallback
    //
    //    All processor events:  Events relating to this processor object
    //
    //    Examples:  Attribute changes, freeze/thaw notifications,
    //               Add/Remove controls, etc.
    //
    virtual EUAPI_FUNC void OnProcessorCallback( tEVT              iEventType,
                                                 NEuCon::uint32    iEventFlags,
                                                 void*             iCallbackEventData = NULL );



    /////////////////////////////////////////////////////////////////////////////////////////////////////
    // The unique ID (persistence ID) used for this processor.  This may be non-human-readable form.
    //
    EUAPI_FUNC tERR SetPersistenceID(const tEuString& iPersistID);

    // A human-readable name you, as a developer/modeler, would use to identify this object.  Not for end users.
    EUAPI_FUNC tERR SetSimpleFriendlyName(const tEuString& iFriendlyName);

    // The name that end-users might see
    EUAPI_FUNC tERR SetUserVisibleName(const tEuString& iVisibleName);


    EUAPI_FUNC tERR GetAssignedTo(std::vector<EuSurfaceBrowser>& oSurfaces) const;

    EUAPI_FUNC tERR AssignTo(const tEuString& iSurfaceFullInternalName);
    EUAPI_FUNC tERR AssignTo(const EuSurfaceBrowser& iSurfaceBrowser);

    // Get an EuProcessorBrowser object for this EuProcessor.
    EUAPI_FUNC tERR GetEuProcessorBrowser( EuProcessorBrowser** oppThisProcessorBrowser ) const;

    /////////////////////////////////////////////////////////////////
    //
    //  Refer to EuCommon base class for Attribute methods.
    //
    //    (SetAttribute, GetAttribute, and DeleteAttribute)
    //
    /////////////////////////////////////////////////////////////////


    EUAPI_FUNC void GetSurfaceIsVisible( bool& iIsVisible ) const;


    ////////////////////////////////////////////////////////////////////////////////////////////////////////////
    // These routines are called by a processor code to notify the surface controls to:
    EUAPI_FUNC tERR Freeze();   // Tell all Surface primitives in this control: do not send updates.
    EUAPI_FUNC tERR Refresh(); // Tell all Surface primitives in this control: Update the surface with a new state (e.g., the table size and values have been altered.
    EUAPI_FUNC tERR Thaw(); // Tell all Surface primitives in this control: resume sending updates.


    // Reserved for use by EuCon
    EUAPI_FUNC tERR  EuProcessorCommand( NEuCon::uint32 iCommandID,      NEuCon::uint32 iIntParam1,       NEuCon::uint32 iIntParam2,
                                         NEuCon::uint32& oIntParam,      void*  ioVoidPtr1 = NULL,        void*  ioVoidPtr2 = NULL   );

protected:
    EuProcessor(const EuProcessor&);                // disallowed
    bool operator=(const EuProcessor&);             // disallowed

public:
    // Reserved, and new for EuCon 2.0
    typedef void (*tOnConfirmValueCBV21)(NEuCon::tOpaquePtr iObj, NEuCon::uint32 iEventFlags, NEuCon::uint32 iControlId, NEuCon::uint32 iArrayMemberControlId,
                                         NEuCon::uint32 iPrimitiveId, NEuCon::tOpaquePtr iAffectedPrimitive, NEuCon::uint16* ioRequestedNewValueIndex);
    typedef void (*tOnPrimitiveCBV21)(NEuCon::tOpaquePtr iObj, NEuCon::int32 iEventType, NEuCon::uint32 iEventFlags, NEuCon::uint32 iControlId, NEuCon::uint32 iArrayMemberControlId,
                                      NEuCon::uint32 iPrimitiveId,  NEuCon::tOpaquePtr iAffectedPrimitive, NEuCon::tOpaquePtr iAffectedPrimitiveLegacy, NEuCon::int32 iAffectedPrimitiveType,
                                      NEuCon::uint16 iNewValueIndex, NEuCon::tOpaquePtr iCallbackEventData);
    typedef void (*tOnControlCBV21)(NEuCon::tOpaquePtr iObj, NEuCon::int32 iEventType, NEuCon::uint32 iEventFlags, NEuCon::uint32 iControlId, NEuCon::uint32 iArrayMemberControlId,
                                    NEuCon::tOpaquePtr iAffectedControl, NEuCon::tOpaquePtr iCallbackEventData);
    typedef void (*tOnProcessorCBV21)(NEuCon::tOpaquePtr iObj, NEuCon::int32 iEventType, NEuCon::uint32 iEventFlags, NEuCon::tOpaquePtr iCallbackEventData);

private:
    tERR RegisterOnConfirmValueCallback(EuProcessor::tOnConfirmValueCBV21 iOnConfirmValueCallback);
    tERR RegisterOnPrimitiveCallback(EuProcessor::tOnPrimitiveCBV21 iOnPrimitiveCallback);
    tERR RegisterOnControlCallback(EuProcessor::tOnControlCBV21 iOnControlCallback);
    tERR RegisterOnProcessorCallback(EuProcessor::tOnProcessorCBV21 iOnProcessorCallback);

};

#endif  // !defined(__EUPHONIX_EUPROCESSOR_H__)