#ifndef TDx_InputEffectH #define TDx_InputEffectH // ========================================================================== // File: TDx_InputEffect.H // Authors: BCB_Code_Generator v1.62, // Darren Dwyer (source code, documentation, demos, website), // Hugh Edwards (documentation, icons, website), // Brian Austin (some source code, documentation) // Description: This file defines the TDx_InputEffect Component // // "TDx_Input_Library v1.62" // (c) 2002 BCB-Tools.com Pty. Ltd., Sydney, Australia. // All Rights Reserved. // // Refer to the 'Licence.Txt' file for licencing & copyright information. // ========================================================================== // -------------------------------------------------------------------------- // #includes // -------------------------------------------------------------------------- #include #include #include #include // -------------------------------------------------------------------------- #include "TDx_Library_Defns.H" #include "TDx_Library_Functions.H" // -------------------------------------------------------------------------- #include "TDx_Input_Library_Defns.H" #include "TDx_Input_Library_Functions.H" // -------------------------------------------------------------------------- // external classes used by the TDx_InputEffect component. class TDx_InputDevice; // -------------------------------------------------------------------------- // external classes used by TDx_InputEffect methods. class TDIEffEscape; class TDIEffect; // -------------------------------------------------------------------------- // ========================================================================== // Class: TDx_InputEffect // Description: The TDx_InputEffect component wraps the DirectX // IDirectInputEffect interface used for managing the force // feedback effects of a device. // // To create a IDirectInputEffect interface, use the // TDx_InputEffect::Create() method and to destroy the // interface, use the TDx_InputEffect::Destroy() method. Note // that you can also use the TDx_InputDevice::CreateEffect() // method for creating the device, however this does not trigger // the TDx_InputEffect::OnCreate() events. // // Use the TDx_InputEffect::OnCreate() event and // TDx_InputEffect::OnDestroy() events to simplify the creation // and destruction of dependent objects. // // Once created, call any of the TDx_InputEffect methods and // handle any error results using the TDx_InputEffect::OnError() // event and the TDx_InputEffect::ErrorValue property. // ========================================================================== #if (__BORLANDC__ >= 0x0530) // BCB Version 3 + class PACKAGE TDx_InputEffect : public TComponent { // -------------------------------------------------------------------------- #else // BCB Version 1 class TDx_InputEffect : public TComponent { #endif // ========================================================================== __published: // ========================================================================== // ---------------------------------------------------------------------- // Event: OnCreate() // Description: The OnCreate() event is triggered by the // TDx_InputEffect::Create() method after it has // successfully created the internal LPDIRECTINPUTEFFECT // used within the TDx_InputEffect component. // // Note that since this event is only called upon successful // creation, this event is an ideal place for code that is // to be activated only once, immediately upon the // successful creation of the LPDIRECTINPUTEFFECT interface. // // For example, you could retrieve the TDx_InputEffect // component's capabilities, Create() dependant components, // allocate memory, etc. // // When used in conjunction with the // TDx_InputEffect::OnDestroy() event, you can fully // automate and insulate your code on a per-component basis. // ---------------------------------------------------------------------- __property TDx_Event OnCreate = {read=FOnCreate, write=FOnCreate, nodefault}; // ---------------------------------------------------------------------- // Event: OnDestroy() // Description: The OnDestroy() event is triggered by the // TDx_InputEffect::Destroy() method, just before the // TDx_InputEffect internal LPDIRECTINPUTEFFECT interface is // destroyed. // // Note: This event is an ideal place to place code that // reverses the results of the TDx_InputEffect::OnCreate() // event. For example, assume you have already setup the // TDx_InputEffect::OnCreate() event to retrieve the // component's capabilities, Create() a dependant component // and allocate some memory; // You can then fully automate and insulate your code on a // per-component basis by placing code in the // TDx_InputEffect::OnDestroy() event to deallocate memory, // Destroy() the dependant components and, when required, // destroy the capabilities component. // ---------------------------------------------------------------------- __property TDx_Event OnDestroy = {read=FOnDestroy, write=FOnDestroy, nodefault}; // ---------------------------------------------------------------------- // Event: OnError() // Description: The OnError event is called when an error occurs in the // TDx_InputEffect component. // ---------------------------------------------------------------------- __property TDx_Error OnError = {read=FOnError, write=FOnError, nodefault}; // ========================================================================== public: // ========================================================================== // ---------------------------------------------------------------------- // Property: Created // Description: The Created property is true if the internal // LPDIRECTINPUTEFFECT used in this component has been // successfully created, otherwise Created is false. // // To create the internal LPDIRECTINPUTEFFECT, call the // TDx_InputEffect::Create() method. // ---------------------------------------------------------------------- __property bool Created = { read=FGetCreated, write=FSetCreated, default=false }; // ---------------------------------------------------------------------- // Property: ErrorValue // Description: The ErrorValue property contains the last error value // returned from a call to a TDx_InputEffect method or // fget/fset. eg. DI_OK or DDERR_SURFACELOST or TDX_ERROR // ---------------------------------------------------------------------- __property HRESULT ErrorValue = { read=FGetErrorValue, write=FSetErrorValue, default=DI_OK }; // ---------------------------------------------------------------------- // Method: Create() // Description: The Create() method is used to automatically create the // internal LPDIRECTINPUTEFFECT interface used in the // TDx_InputEffect component and must be called before any // methods of the TDx_InputEffect component will function. // Params: pGuid - // Contains the GUID of the Effect to create. // Possible values are: // // GUID_ConstantForce // GUID_RampForce // GUID_Square // GUID_Sine // GUID_Triangle // GUID_SawtoothUp // GUID_SawtoothDown // GUID_Spring // GUID_Damper // GUID_Inertia // GUID_Friction // GUID_CustomForce // pEffect - // A pointer to a TDIEffect object that contains information // about the effect to be created. // pInput - // A pointer to the TDx_InputDevice object that the effect // is to be created for. // ---------------------------------------------------------------------- virtual bool __fastcall Create( GUID pGuid, TDIEffect* pEffect, TDx_InputDevice* pInput ); // ---------------------------------------------------------------------- // Method: Destroy() // Description: The Destroy() method is used to automatically destroy the // internal LPDIRECTINPUTEFFECT interface used in the // TDx_InputEffect component and should be called when the // internal interface is no longer required. // // Note: This method is called by the component's // destructor. // ---------------------------------------------------------------------- virtual bool __fastcall Destroy(); // ---------------------------------------------------------------------- // Method: Download() // Description: The Download() method will download an effect to a // device, updating any effect properties that may have been // modified using TDx_InputEffect::SetParameters() since the // last Download() call. // // Effect properties specified in // TDIEffectInfo::DynamicParams can be modified while the // effect is still playing. // // Error values that can be generated are: // // DIERR_NOTINITIALIZED // DIERR_DEVICEFULL // DIERR_INCOMPLETEEFFECT // DIERR_INPUTLOST // DIERR_NOTEXCLUSIVEACQUIRED // DIERR_INVALIDPARAM // DIERR_EFFECTPLAYING // ---------------------------------------------------------------------- virtual bool __fastcall Download(); // ---------------------------------------------------------------------- // Method: Escape() // Description: The Escape() method will send a hardware-specific command // directly to the device driver. // // TDIDeviceInstance::FFDriver should be checked against the // expected driver identifier to ensure the escape is sent // to the right driver. // // The driver documentation should list and describe the // comands that are valid for the driver. // // Error values that can be generated are: // // DIERR_NOTINITIALIZED // DIERR_DEVICEFULL // Params: pEffectEscape - // The EffectEscape parameter references a TDIEffEscape // component describing the command to be sent to the // driver. // // On returning, the TDIEffEscape::OutBufferSize property // will define amount of data, in bytes, written to // TDIEffEscape::OutBuffer. // ---------------------------------------------------------------------- virtual bool __fastcall Escape( TDIEffEscape* pEffectEscape ); // ---------------------------------------------------------------------- // Method: GetEffectGuid() // Description: The GetEffectGuid() method retrieves the GUID identifying // the effect described by this TDx_InputEffect object. // Once the GUID is obtained, more effect information can be // retrieved with TDx_InputDevice::GetEffectInfo(). // // Error values that can be generated are: // // DIERR_INVALIDPARAM // DIERR_NOTINITIALIZED // Params: pGUID - // Contains a GUID object for holding the effect GUID if // this method returns successfully. // ---------------------------------------------------------------------- virtual bool __fastcall GetEffectGuid( GUID* pGUID ); // ---------------------------------------------------------------------- // Method: GetEffectStatus() // Description: The GetEffectStatus() method will return the effect's // current status. // // Error values that can be generated are: // // DIERR_INVALIDPARAM // DIERR_NOTINITIALIZED // Params: pFlags - // The Flags parameter defines flags indicating the current // status of the effect. // The described effect applies when the flag is set. // Flags: // DIEGES_EMULATED - // The effect is being emulated by TDx_Input. // DIEGES_PLAYING - // This effect is currently playing. // ---------------------------------------------------------------------- virtual bool __fastcall GetEffectStatus( dword* pFlags ); // ---------------------------------------------------------------------- // Method: GetParameters() // Description: The GetParameters() method retrieves the current settings // of the effect. // // Error values that can be generated are: // // DIERR_INVALIDPARAM // DIERR_MOREDATA // DIERR_NOTINITIALIZED // Params: pEffect - // The Effect parameter references a TDIEffect component for // holding the effect information if this method returns // successfully. // pFlags - // The Flags parameter defines flags indicating which // properties of the TDIEffect component referenced by the // Effect parameter are to be retrieved. // The described effect applies when the flag is set. // Flags: // DIEP_ALLPARAMS - // All the TDIEffect properties are to be retrieved. // // This is equivilent to setting all the other flags // of this parameter. // DIEP_ALLPARAMS_DX5 - // All the TDIEffect properties except // TDIEffect::StartDelay are to be retrieved. // // This is equivilent to setting all the other flags // of this parameter except DIEP_STARTDELAY. // DIEP_AXES - // TDIEffect::NumAxes and TDIEffect::Axes are to be // retrieved. // // TDIEffect::NumAxes holds the size of the buffer // referenced by TDIEffect::Axes. // When the TDIEffect::Axes buffer is too small, a // DIERR_MOREDATA error is generated and // TDIEffect::NumAxes will indicate the required // buffer size. // DIEP_DIRECTION - // TDIEffect::NumAxes and TDIEffect::Direction are to // be retrieved. // // TDIEffect::NumAxes holds the size of the buffer // referenced by TDIEffect::Direction. // When the TDIEffect::Direction buffer is too small, // a DIERR_MOREDATA error is generated and // TDIEffect::NumAxes will indicate the required // buffer size. // // One or more of the DIEFF_CARTESIAN, DIEFF_POLAR or // DIEFF_SPHERICAL flags must be set in // TDIEffect::Flags to indicate in which coordinate // system the directions should be reported. // Setting all three will result in the coordinates // being retrieved using the same system as when they // were set. // On returning, only one of the coordinate system // flags will be set, indicating how the // TDIEffect::Direction coordinates should be // interpreted. // DIEP_DURATION - // TDIEffect::Duration is to be retrieved. // DIEP_ENVELOPE - // The TDIEnvelope component referenced by // TDIEffect::Envelope is to be filled and retrieved. // // When there is no envelope TDIEffect::Envelope will // be NULL when the method returns. // DIEP_GAIN - // TDIEffect::GAIN is to be retrieved. // DIEP_SAMPLEPERIOD - // TDIEffect::SamplePeriod is to be retrieved. // DIEP_STARTDELAY - // TDIEffect::StartDelay is to be retrieved. // DIEP_TRIGGERBUTTON - // TDIEffect::TriggerButton is to be retrieved. // DIEP_TRIGGERREPEATINTERVAL - // TDIEffect::TriggerRepeatInterval is to be // retrieved. // DIEP_TYPESPECIFICPARAMS - // Any type specific parameters referenced by // TDIEffect::TypeSpecificParams are retrieved. // // TDIEffect::TypeSpecificParamsSize initially holds // the size the TDIEffect::TypeSpecificParams buffer // and the actual amount of data written to the buffer // on return. // When the TDIEffect::TypeSpecificParams buffer is // too small, a DIERR_MOREDATA error is generated and // TDIEffect::TypeSpecificParamsSize will indicate the // required buffer size. // ---------------------------------------------------------------------- virtual bool __fastcall GetParameters( TDIEffect* pEffect, dword pFlags ); // ---------------------------------------------------------------------- // Method: SetParameters() // Description: The SetParameters() method sets the properties of this // effect. // // Only one or less of the DIEP_NODOWNLOAD, DIEP_START and // DIEP_NORESTART flags should be set in the Flags parameter // of this method. // // The effect will be automatically downloaded to the device // unless the DIEP_NODOWNLOAD flag is set. // // TDIEffectInfo::DynamicParams indicates which parameters // may be dynamically updated while the effect is playing. // // Updating an effects parameters while it is playing causes // the effect to behave as if the new parameters are the // ones with which it started playing. // For example : If a 10 second effect is playing, and the // duration of the effect is changed to 4 seconds, the // effect will stop 4 seconds after it began. If the effect // has been going for more than four seconds, it will stop // immediately. // // Error values that can be generated are: // // DIERR_NOTINITIALIZED // DIERR_INCOMPLETEEFFECT // DIERR_INPUTLOST // DIERR_INVALIDPARAM // DIERR_EFFECTPLAYING // Params: pEffect - // The Effect parameter references a TDIEffect component for // holding the effect information if this method returns // successfully. // pFlags - // The Flags parameter defines flags indicating which // properties of TDIEffect contain valid data and how that // data should be applied to the device. // The described effect applies when the flag is set. // Flags: // DIEP_AXES - // TDIEffect::NumAxes and TDIEffect::Axes hold valid // data. // // TDIEffect::NumAxes should hold the size of the // buffer referenced by TDIEffect::Axes. // DIEP_DIRECTION - // TDIEffect::NumAxes and TDIEffect::Direction hold // valid data. // // TDIEffect::NumAxes should hold the size of the // buffer referenced by TDIEffect::Direction. // // One of the DIEFF_CARTESIAN, DIEFF_POLAR or // DIEFF_SPHERICAL flags must be set in // TDIEffect::Flags to indicate which coordinate // system is being used. // DIEP_DURATION - // TDIEffect::Duration holds valid data. // DIEP_ENVELOPE - // The TDIEnvelope component referenced by // TDIEffect::Envelope contains valid data. // // Setting TDIEffect::Envelope to NULL with this flag // set will detach any existing envelope from this // effect. // DIEP_GAIN - // TDIEffect::Gain holds valid data. // DIEP_NODOWNLOAD - // The updated properties should not be downloaded to // the device until TDx_InputEffect::Download() is // called. // DIEP_NORESTART - // If the effect is already playing, it should not be // stopped and restarted in order to update its // properties. // // This means that if the driver doesnt support "on // the fly" modifications and this flag is set, the // effect parameters will not be updated and a // DIERR_EFFECTPLAYING error returned. // DIEP_SAMPLEPERIOD - // TDIEffect::SamplePeriod holds valid data. // DIEP_START - // The effect should be started or restarted after the // properties are updated. // DIEP_STARTDELAY - // TDIEffect::StartDelay holds valid data. // DIEP_TRIGGERBUTTON - // TDIEffect::TriggerButton holds valid data. // DIEP_TRIGGERDELAY - // TDIEffect::TriggerDelay holds valid data. // DIEP_TRIGGERREPEATINTERVAL - // TDIEffect::TriggerRepeatInterval holds valid data. // DIEP_TYPESPECIFICPARAMS - // TDIEffect::TypeSpecificParams and // TDIEffect::TypeSpecificParamsSize contain valid // data. // // TDIEffect::TypeSpecificParamsSize holds the size of // the data referenced by // TDIEffect::TypeSpecificParams. // ---------------------------------------------------------------------- virtual bool __fastcall SetParameters( TDIEffect* pEffect, dword pFlags ); // ---------------------------------------------------------------------- // Method: Start() // Description: The Start() method downloads and plays an effect from the // beginning, restarting the effect if neccessary. // // The download only occurs when the effect has been // modified or is not already present and the // DIES_NODOWNLOAD flag is not set. // // Exclusive level access to the acquired device is // required. // // Error values that can be generated are: // // DIERR_INVALIDPARAM // DIERR_INCOMPLETEEFFECT // DIERR_NOTEXCLUSIVEACQUIRED // DIERR_NOTINITIALIZED // DIERR_UNSUPPORTED // Params: pIterations - // The Iterations parameter defines how many times the // effect should be played. // // This value can be set from 1 to INFINITE, but not all // devices support multiple iterations. // // If the effect has an envelope, it will be applied each // time the effect is repeated. // // To play an effect indefinitely without re-applying the // envelope each time, change TDIEffect::Duration to // INFINITE with TDx_InputEffect::SetParameters(). // pFlags - // The Flags parameter defines flags indicating how the // device should play the effect. // The described effect applies when the flag is set. // Flags: // DIES_NODOWNLOAD - // The effect should not be automatically downloaded // to the device. // DIES_SOLO - // Clear all other effects from the device before // playing starting this one. // ---------------------------------------------------------------------- virtual bool __fastcall Start( dword pIterations, dword pFlags ); // ---------------------------------------------------------------------- // Method: Stop() // Description: The Stop() method will halt the playing of an effect. // // Exclusive level access to the acquired device the effect // is playing on is required. // // Error values that can be generated are: // // DIERR_NOTEXCLUSIVEACQUIRED // DIERR_NOTINITIALIZED // ---------------------------------------------------------------------- virtual bool __fastcall Stop(); // ---------------------------------------------------------------------- // Method: Unload() // Description: The Unload() method will stop and remove the effect from // the device. // // Error values that can be generated are: // // DIERR_INPUTLOST // DIERR_INVALIDPARAM // DIERR_NOTEXCLUSIVEACQUIRED // DIERR_NOTINITIALIZED // ---------------------------------------------------------------------- virtual bool __fastcall Unload(); // ---------------------------------------------------------------------- // Constructor() and Destructor() // ---------------------------------------------------------------------- __fastcall TDx_InputEffect(TComponent* Owner); virtual __fastcall ~TDx_InputEffect(); // ---------------------------------------------------------------------- // The following properties and methods are used internally by // TDx_Input_Library and should not be used. // ---------------------------------------------------------------------- __property LPDIRECTINPUTEFFECT Internal_LPDIRECTINPUTEFFECT = { read=FGetInternal_LPDIRECTINPUTEFFECT, write=FSetInternal_LPDIRECTINPUTEFFECT, nodefault }; __property LPDIRECTINPUTEFFECT* Internal_LPDIRECTINPUTEFFECT_Ptr = { read=FGetInternal_LPDIRECTINPUTEFFECT_Ptr, nodefault }; void __fastcall Internal_LPDIRECTINPUTEFFECT_Update(); // ========================================================================== protected: // ========================================================================== // ---------------------------------------------------------------------- // Property Access Methods // ---------------------------------------------------------------------- bool __fastcall FGetCreated(); void __fastcall FSetCreated( bool pCreated ); HRESULT __fastcall FGetErrorValue(); void __fastcall FSetErrorValue( HRESULT pErrorValue ); // ========================================================================== private: // ========================================================================== // ---------------------------------------------------------------------- // Internal Interface Access // ---------------------------------------------------------------------- LPDIRECTINPUTEFFECT __fastcall FGetInternal_LPDIRECTINPUTEFFECT(); void __fastcall FSetInternal_LPDIRECTINPUTEFFECT( LPDIRECTINPUTEFFECT pLPDIRECTINPUTEFFECT ); LPDIRECTINPUTEFFECT* __fastcall FGetInternal_LPDIRECTINPUTEFFECT_Ptr(); // ---------------------------------------------------------------------- // Property Variables // ---------------------------------------------------------------------- bool fCreated; HRESULT fErrorValue; // ---------------------------------------------------------------------- // Interface Variables // ---------------------------------------------------------------------- LPDIRECTINPUTEFFECT fLPDIRECTINPUTEFFECT; // ---------------------------------------------------------------------- // Event Variables // ---------------------------------------------------------------------- TDx_Event FOnCreate; TDx_Event FOnDestroy; TDx_Error FOnError; }; // -------------------------------------------------------------------------- #endif // --------------------------------------------------------------------------