== Draft ==

'''THIS PAGE IS A WORK IN PROGRESS''' ... Please make edits to this page to improve it!


= SDL_HapticPeriodic =
A structure that contains a template for a periodic effect.


== Data Fields ==
{|
|
|
|<bgcolor="#EDEDED">''Header''
|-
|Uint16
|'''type'''
|the shape of the waves; <!-- one of the effects handled by this structure --> see [[#type|Remarks]] for details
|-
|[[SDL_HapticDirection]]
|'''direction'''
|direction of the effect (relative to the user)
|-
|
|
|<bgcolor="#EDEDED">''Replay''
|-
|Uint32
|'''length'''
|duration of the effect <!-- (is this the same as # of cycles? always in ms?) --> 
|-
|Uint16
|'''delay'''
|delay before starting the effect <!-- (ms?) --> 
|-
|
|
|<bgcolor="#EDEDED">''Trigger''
|-
|Uint16
|'''button'''
|button that triggers the effect
|-
|Uint16
|'''interval'''
|how soon it can be triggered again after '''button''' <!-- (ms?) (delay between individual waves or before the effect can be used again?) --> 
|-
|
|
|<bgcolor="#EDEDED">''Periodic''
|-
|Uint16
|'''period'''
|period of the wave <!-- (ms?) (like frequency, duration from start to start?) --> 
|-
|Sint16
|'''magnitude'''
|peak value; if negative, equivalent to 180 degrees extra phase shift <!-- (units?) (like amplitude?) --> 
|-
|Sint16
|'''offset'''
|mean value of the wave <!-- (what aspect of the wave is being offset from what other marker? Is this the distance between waves?) --> 
|-
|Uint16
|'''phase'''
|positive phase shift given by hundredth of a degree; see [[#phase|Remarks]] for details <!-- (Is this what creates the flat tops? What is the definition of a cycle, 1 sec?) --> 
|-
|
|
|<bgcolor="#EDEDED">''Envelope''
|-
|Uint16
|'''attack_length'''
|duration of the attack <!-- (ms?) --> 
|-
|Uint16
|'''attack_level'''
|level at the start of the attack <!-- (units?) --> 
|-
|Uint16
|'''fade_length'''
|duration of the fade <!-- (ms?) --> 
|-
|Uint16
|'''fade_level'''
|level at the end of the fade <!-- (units?) --> 
|}

== Remarks ==
<!-- There are several typing and grammatical errors in this section of the header. May not require fixing but probably should at least be looked at. Changes from header have been made below. -->

<span id="type"></span>
A periodic effect consists of a wave-shaped effect that repeats itself over time. The type determines the shape of the wave and the other parameters determine the dimensions of the wave.
```
button         period
press          |     |
  ||      __    __    __    __    __    _
  ||     |  |  |  |  |  |  |  |  |  |   magnitude
  \/     |  |__|  |__|  |__|  |__|  |   _
    -----
      |            offset?
    delay          phase?

-------------------------------------
              length
===================================================
                      interval
```
<!-- Does this structure warrant a simple .bmp diagram? Something that can use colors and such? -->

'''type''' may be one of the following:
{|
|SDL_HAPTIC_SINE
|<code>  __      __      __      __</code><br/><code> /  \    /  \    /  \    /</code><br/><code>/    \__/    \__/    \__/</code>
|-
|SDL_HAPTIC_TRIANGLE
|<code>  /\    /\    /\    /\    /\</code><br/><code> /  \  /  \  /  \  /  \  /</code><br/><code>/    \/    \/    \/    \/</code>
|-
|SDL_HAPTIC_SAWTOOTHUP
|<code>  /|  /|  /|  /|  /|  /|  /|</code><br/><code> / | / | / | / | / | / | / |</code><br/><code>/  |/  |/  |/  |/  |/  |/  |</code>
|-
|SDL_HAPTIC_SAWTOOTHDOWN
|<code>\  |\  |\  |\  |\  |\  |\  |</code><br/><code> \ | \ | \ | \ | \ | \ | \ |</code><br/><code>  \|  \|  \|  \|  \|  \|  \| </code>
|}

<!-- ||SDL_HAPTIC_SQUARE||<code> __    __    __    __    __</code><br/><code>|  |  |  |  |  |  |  |  |  |</code><br/><code>|  |__|  |__|  |__|  |__|  |</code>|| -->

<span id="phase"></span>'''phase''' is given by hundredths of a degree, meaning that giving the phase a value of 9000 will displace it 25% of its period. Here are sample values:
{|
|0
|No phase displacement
|-
|9000
|Displaced 25% of its period
|-
|18000
|Displaced 50% of its period
|-
|27000
|Displaced 75% of its period
|-
|36000
|Displaced 100% of its period, same as 0, but 0 is preferred
|}
<!-- This is not at all clear unless it is a common thing that a programmer would know.  Is phase describing the duration of an individual wave from start to finish or the duration from the start of one wave to the start of the next? -->

== Related Structures ==
:[[SDL_HapticDirection]]

== Related Functions ==
:[[SDL_HapticNewEffect]]

----
[[CategoryStruct]], [[CategoryForceFeedback]], [[CategoryDraft]]