You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
189 lines
6.8 KiB
189 lines
6.8 KiB
<html>
|
|
<link rel=stylesheet href=style.css>
|
|
<link rel="icon" href="icon.png" type="image/png">
|
|
|
|
<img src=logo.png style="width: 80%; display: block; margin-left: auto; margin-right: auto;">
|
|
|
|
<h2>Introduction to the StepManiaX SDK</h2>
|
|
|
|
The StepManiaX SDK supports C++ development for the <a href=https://stepmaniax.com/>StepManiaX dance platform</a>.
|
|
<p>
|
|
SDK support: <a href=mailto:sdk@stepmaniax.com>sdk@stepmaniax.com</a>
|
|
|
|
<h2>Usage</h2>
|
|
|
|
You can either build the solution and link the resulting SMX.dll to your application,
|
|
or import the source project and add it to your Visual Studio solution. The SDK
|
|
interface is <code>SMX.h</code>.
|
|
<p>
|
|
See <code>SMXSample</code> for a sample application.
|
|
<p>
|
|
Up to two controllers are supported. <code>SMX_GetInfo</code> can be used to check which
|
|
controllers are connected. Each <code>pad</code> argument to API calls can be 0 for the
|
|
player 1 pad, or 1 for the player 2 pad.
|
|
|
|
<h2>HID support</h2>
|
|
|
|
The platform can be used as a regular USB HID input device, which works in any game
|
|
that supports input remapping.
|
|
<p>
|
|
However, applications using this SDK to control the panels directly should ignore the
|
|
HID interface, and instead use <code>SMX_GetInputState</code> to retrieve the input state.
|
|
|
|
<h2>Platform lights</h2>
|
|
|
|
The platform can have up to nine panels. Each panel has a grid of 4x4 RGB LEDs, which can
|
|
be individually controlled at up to 30 FPS.
|
|
<p>
|
|
See <code>SMX_SetLights2</code>.
|
|
|
|
<h2>Update notes</h2>
|
|
|
|
2019-07-18-01: Added SMX_SetLights2. This is the same as SMX_SetLights, with an added
|
|
parameter to specify the size of the buffer. This must be used to control the Gen4
|
|
pads which have additional LEDs.
|
|
|
|
<h2>Platform configuration</h2>
|
|
|
|
The platform configuration can be read and modified using SMX_GetConfig and SMX_SetConfig.
|
|
Most of the platform configuration doesn't need to be accessed by applications, since
|
|
users can use the SMXConfig application to manage their platform.
|
|
<p>
|
|
<ul>
|
|
<li>
|
|
<b>enabledSensors</b>
|
|
<p>
|
|
Each platform can have up to nine panels in any configuration, but most devices have
|
|
a smaller number of panels installed. If an application wants to adapt its UI to the
|
|
user's panel configuration, see enabledSensors to detect which sensors are enabled.
|
|
<p>
|
|
Each panel has four sensors, and if a panel is disabled, all four of its sensors will be
|
|
disabled. Disabling individual sensors is possible, but removing individual sensors
|
|
reduces the performance of the pad and isn't recommended.
|
|
<p>
|
|
Note that this indicates which panels the player is using for input. Other panels may
|
|
still have lights support, and the application should always send lights data for all
|
|
possible panels even if it's not being used for input.
|
|
</li>
|
|
</ul>
|
|
|
|
<h2>Reference</h2>
|
|
|
|
<h3 class=ref>void SMX_Start(SMXUpdateCallback UpdateCallback, void *pUser);</h3>
|
|
|
|
Initialize, and start searching for devices.
|
|
<p>
|
|
UpdateCallback will be called when something happens: connection or disconnection, inputs
|
|
changed, configuration updated, test data updated, etc. It doesn't specify what's changed,
|
|
and the user should check all state that it's interested in.
|
|
<p>
|
|
This is called asynchronously from a helper thread, so the receiver must be thread-safe.
|
|
|
|
<h3 class=ref>void SMX_Stop();</h3>
|
|
|
|
Shut down and disconnect from all devices. This will wait for any user callbacks to complete,
|
|
and no user callbacks will be called after this returns.
|
|
|
|
<h3 class=ref>void SMX_SetLogCallback(SMXLogCallback callback);</h3>
|
|
|
|
Set a function to receive diagnostic logs. By default, logs are written to stdout.
|
|
This can be called before SMX_Start, so it affects any logs sent during initialization.
|
|
|
|
<h3 class=ref>void SMX_GetInfo(int pad, SMXInfo *info);</h3>
|
|
|
|
Get info about a pad. Use this to detect which pads are currently connected.
|
|
|
|
<h3 class=ref>uint16_t SMX_GetInputState(int pad);</h3>
|
|
|
|
Get a mask of the currently pressed panels.
|
|
|
|
<h3 class=ref>void SMX_SetLights(const char lightsData[864]);</h3>
|
|
|
|
(deprecated)
|
|
<p>
|
|
Equivalent to SMX_SetLights2(lightsData, 864). SMX_SetLights2 should be used instead.
|
|
|
|
<h3 class=ref>void SMX_SetLights2(const char *lightsData, int lightDataSize);</h3>
|
|
Update the lights. Both pads are always updated together. lightsData is a list of 8-bit RGB
|
|
colors, one for each LED.
|
|
<p>
|
|
lightDataSize is the number of bytes in lightsData. This should be 1350 (2 pads * 9 panels *
|
|
25 lights * 3 RGB colors). For backwards-compatibility, this can also be 864.
|
|
<p>
|
|
Each panel has lights in the following order:
|
|
<p>
|
|
<pre>
|
|
00 01 02 03
|
|
16 17 18
|
|
04 05 06 07
|
|
19 20 21
|
|
08 09 10 11
|
|
22 23 24
|
|
12 13 14 15
|
|
</pre>
|
|
|
|
Each panel has lights in the following order:
|
|
<p>
|
|
<pre>
|
|
0123
|
|
4567
|
|
89AB
|
|
CDEF
|
|
</pre>
|
|
<p>
|
|
Panels are in the following order:
|
|
<p>
|
|
<pre>
|
|
012 9AB
|
|
345 CDE
|
|
678 F01
|
|
</pre>
|
|
|
|
Lights will update at up to 30 FPS. If lights data is sent more quickly, a best effort will be
|
|
made to send the most recent lights data available, but the panels won't update more quickly.
|
|
<p>
|
|
The panels will return to automatic lighting if no lights are received for a while, so applications
|
|
controlling lights should send light updates continually, even if the lights aren't changing.
|
|
<p>
|
|
For backwards compatibility, if lightDataSize is 864, the old 4x4-only order is used,
|
|
which simply omits lights 16-24.
|
|
|
|
<h3 class=ref>void SMX_ReenableAutoLights();</h3>
|
|
|
|
By default, the panels light automatically when stepped on. If a lights command is sent by
|
|
the application, this stops happening to allow the application to fully control lighting.
|
|
If no lights update is received for a few seconds, automatic lighting is reenabled by the
|
|
panels.
|
|
<p>
|
|
<code>SMX_ReenableAutoLights</code> can be called to immediately reenable auto-lighting, without waiting
|
|
for the timeout period to elapse. Games don't need to call this, since the panels will return
|
|
to auto-lighting mode automatically after a brief period of no updates.
|
|
|
|
<h3 class=ref>void SMX_GetConfig(int pad, SMXConfig *config);</h3>
|
|
|
|
Get the current controller's configuration.
|
|
|
|
<h3 class=ref>void SMX_SetConfig(int pad, const SMXConfig *config);</h3>
|
|
|
|
Update the current controller's configuration. This doesn't block, and the new configuration will
|
|
be sent in the background. SMX_GetConfig will return the new configuration as soon as this call
|
|
returns, without waiting for it to actually be sent to the controller.
|
|
|
|
<h3 class=ref>void SMX_FactoryReset(int pad);</h3>
|
|
|
|
Reset a pad to its original configuration.
|
|
|
|
<h3 class=ref>void SMX_ForceRecalibration(int pad);</h3>
|
|
|
|
Request an immediate panel recalibration. This is normally not necessary, but can be helpful
|
|
for diagnostics.
|
|
|
|
<h3 class=ref>
|
|
void SMX_SetTestMode(int pad, SensorTestMode mode);
|
|
<br>
|
|
bool SMX_GetTestData(int pad, SMXSensorTestModeData *data);
|
|
</h3>
|
|
|
|
Set a panel test mode and request test data. This is used by the configuration tool.
|
|
|
|
|
|
|