[Deprecated] Unreal Engine 4 (UE4) Blueprint library to control lighting for Razer Chroma
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
Config
Content
Plugins/ChromaSDKPlugin
Source
UnrealEngineVersionChanger
images
.gitignore
Engine_Switch_4_12.cmd
Engine_Switch_4_13.cmd
Engine_Switch_4_14.cmd
Engine_Switch_4_15.cmd
Engine_Switch_4_16.cmd
Engine_Switch_4_17.cmd
Engine_Switch_4_18.cmd
Launch_Standalone.cmd
OpenPluginBinaries.cmd
README.md
SwitchEngineVersion.cmd
UE4ChromaSDK.uproject
UE4ChromaSDK_4_12.uproject
UE4ChromaSDK_4_13.uproject
UE4ChromaSDK_4_14.uproject
UE4ChromaSDK_4_15.uproject
UE4ChromaSDK_4_16.uproject
UE4ChromaSDK_4_17.uproject
UE4ChromaSDK_4_18.uproject
clean_intermediate_files.cmd
clear_logs.sh
show_logs.sh

README.md

ChromaSDKPlugin - Unreal Engine 4 (UE4) Blueprint library to control lighting for (Razer Chroma)


Note: UE4ChromaSDK is the older plugin and you probably want UE4ChromaSDKRT instead.


Table of Contents

See Also

Apps:

Plugins:

Frameworks supported

  • Windows ChromaSDK (32-bit)
  • Windows ChromaSDK (64-bit)

Prerequisites

image_42

Engine Versions

Releases have binary versions of the Plugin which can be added upon request.

Quick Start

Set of Animations

A set of animations refers to the following given an AnimationName.

AnimationName_ChromaLink.chroma
AnimationName_Headset.chroma
AnimationName_Keyboard.chroma
AnimationName_Keypad.chroma
AnimationName_Mouse.chroma
AnimationName_Mousepad.chroma

API

ChromaSDKPluginBPLibrary - Blueprint Library

ClearAll

ClearAll will issue a CLEAR effect for all devices.

void UChromaSDKPluginBPLibrary::ClearAll();

ClearAnimationType

ClearAnimationType will issue a CLEAR effect for the given device.

void UChromaSDKPluginBPLibrary::ClearAnimationType(const EChromaSDKDeviceEnum& device);

GetAnimationCount

GetAnimationCount will return the number of open animations.

int UChromaSDKPluginBPLibrary::GetAnimationCount();

GetAnimationIdByIndex

GetAnimationIdByIndex will return the animationId given the index of the open animation. The index is zero-based and less than the number returned by GetAnimationCount. Use GetAnimationName to get the name of the animation.

int UChromaSDKPluginBPLibrary::GetAnimationIdByIndex(int index);

GetPlayingAnimationCount

GetPlayingAnimationCount will return the number of playing animations.

int UChromaSDKPluginBPLibrary::GetPlayingAnimationCount();

GetPlayingAnimationId

GetPlayingAnimationId will return the animationId given the index of the playing animation. The index is zero-based and less than the number returned by GetPlayingAnimationCount. Use GetAnimationName to get the name of the animation.

int UChromaSDKPluginBPLibrary::GetPlayingAnimationId(int index);

PlayAnimationComposite

Play a set of *_Device.chroma Animations. With loop set to false, the animations will play once. With loop set to true, the animations will loop.

void UChromaSDKPluginBPLibrary::PlayAnimationComposite(const FString& animationName, bool loop);

StopAnimationComposite

Stop a set of *_Device.chroma Animations

void UChromaSDKPluginBPLibrary::StopAnimationComposite(const FString& animationName);

PlayAnimation

Play the *.chroma Animation. With loop set to false, the animation will play once. With loop set to true, the animation will loop.

void UChromaSDKPluginBPLibrary::PlayAnimation(const FString& animationName, bool loop);

IsAnimationPlaying

Is the *.chroma Animation playing?

bool UChromaSDKPluginBPLibrary::IsAnimationPlaying(const FString& animationName);

IsAnimationTypePlaying

Is the Animation type playing?"

bool UChromaSDKPluginBPLibrary::IsAnimationTypePlaying(const EChromaSDKDeviceEnum& device);

PlayAnimations

Play an array of *.chroma Animations

void UChromaSDKPluginBPLibrary::PlayAnimations(const TArray<FString>& animationNames, bool loop);

StopAnimation

Stop the *.chroma Animation

void UChromaSDKPluginBPLibrary::StopAnimation(const FString& animationName);

StopAnimations

Stop an array *.chroma Animations

void UChromaSDKPluginBPLibrary::StopAnimations(const TArray<FString>& animationNames);

StopAnimationType

Stop playing the Animation type

void UChromaSDKPluginBPLibrary::StopAnimationType(const EChromaSDKDeviceEnum& device);

StopAll

StopAll will automatically stop all animations that are playing.

void UChromaSDKPluginBPLibrary::StopAll();

GetKeyColorName

Get the color from the animation frame's key

FLinearColor  UChromaSDKPluginBPLibrary::GetKeyColorName(const FString& animationName,
    const int frameIndex, const EChromaSDKKeyboardKey& key);

SetKeyColorName

Set the animation frame's key to the supplied color

void UChromaSDKPluginBPLibrary::SetKeyColorName(const FString& animationName,
    const int frameIndex, const EChromaSDKKeyboardKey& key, const FLinearColor& color);

SetKeysColorName

Set the animation frame to the supplied color for a set of keys

void UChromaSDKPluginBPLibrary::SetKeysColorName(const FString& animationName,
    const int frameIndex, const TArray<EChromaSDKKeyboardKey>& keys, const FLinearColor& color);

SetKeyColorAllFramesName

Set the key to the supplied color for all animation frames

void UChromaSDKPluginBPLibrary::SetKeyColorAllFramesName(const FString& animationName,
    const EChromaSDKKeyboardKey& key, const FLinearColor& color);

SetKeysColorAllFramesName

Set the keys to the supplied color for all animation frames

void UChromaSDKPluginBPLibrary::SetKeysColorAllFramesName(const FString& animationName,
    const TArray<EChromaSDKKeyboardKey>& keys, const FLinearColor& color);

CopyKeyColorName

Copy color from a source animation to a target animation for a key

void UChromaSDKPluginBPLibrary::CopyKeyColorName(const FString& sourceAnimationName,
    const FString& targetAnimationName, const int frameIndex, const EChromaSDKKeyboardKey& key);

CopyKeysColorName

Copy color from a source animation to a target animation for a set of keys

void UChromaSDKPluginBPLibrary::CopyKeysColorName(const FString& sourceAnimationName,
    const FString& targetAnimationName, const int frameIndex, const TArray<EChromaSDKKeyboardKey>& keys);

CopyKeysColorAllFramesName

Copy color from a source animation to a target animation for a set of keys for all frames

void UChromaSDKPluginBPLibrary::CopyKeysColorAllFramesName(const FString& sourceAnimationName,
    const FString& targetAnimationName, const TArray<EChromaSDKKeyboardKey>& keys);

CopyNonZeroAllKeysAllFramesName

Copy nonzero colors from a source animation to a target animation for all keys and all frames

void UChromaSDKPluginBPLibrary::CopyNonZeroAllKeysAllFramesName(const FString& sourceAnimationName,
  const FString& targetAnimationName);

CopyNonZeroKeyColorName

Copy nonzero color from a source animation to a target animation for a key

void UChromaSDKPluginBPLibrary::CopyNonZeroKeyColorName(const FString& sourceAnimationName,
    const FString& targetAnimationName, const int frameIndex, const EChromaSDKKeyboardKey& key);

CopyNonZeroKeysColorName

Copy nonzero color from a source animation to a target animation for a set of keys

void UChromaSDKPluginBPLibrary::CopyNonZeroKeysColorName(const FString& sourceAnimationName,
    const FString& targetAnimationName, const int frameIndex, const TArray<EChromaSDKKeyboardKey>& keys);

CopyNonZeroKeysColorAllFramesName

Copy nonzero color from a source animation to a target animation for a set of keys for all frames

void UChromaSDKPluginBPLibrary::CopyNonZeroKeysColorAllFramesName(const FString& sourceAnimationName,
    const FString& targetAnimationName, const TArray<EChromaSDKKeyboardKey>& keys);

GetFrameCountName

Get the .chroma animation frame count

int UChromaSDKPluginBPLibrary::GetFrameCountName(const FString& animationName);

Key Bindings

Games often need to highlight hotkeys that are tied to game play. This can be for general WASD movement, interacting with the game, or display cooldowns.

Just displaying hotkeys by themselves is less visually interesting. Hotkeys can be shown on top of existing .chroma animations.

This allows environmental effects or other animations to be shown as the base layer with hotkeys on top of that.

In the below image, a loaded animation has the hotkeys added to each frame and then the animation plays.

1 When a .chroma animation is referenced by name, it's loaded from the game's Content folder into memory.

2 Make Literal String stores the .chroma animation name which is reused in multiple steps. In this case Random_Keyboard is stored.

2 UnloadAnimationName takes the animation name and unloads the Chroma color frames that were previously loaded so they can be modified.

3 GetFrameCountName takes the animaton name and returns the number of frames in the animation.

4 For Loop is used to iterate over all the frames in the animation.

5 SetKeyColorName takes the animation name, the color frame index, the key binding to update, and the color to show on the key. A constant color could be used, but to be more visually interesting, the example lerps between two colors using the frame index as the increment.

6 PlayAnimation takes the animation name to play the animation after the For Loop completes.

image_45

In the image below, an animation is reloaded from disk to hide the hotkeys.

1 CloseAnimationName takes the animation name and destroys the instance in memory.

2 PlayAnimation loads the animation name from disk in the original state without the hotkeys applied.

This process could be used to hide the hotkeys, or to reload the animation after the keybindings change to highlight new keys.

image_46

In the image below, a source animation color can be copied into a target animation. In this case a fire animation can play on selected hotkeys.

CopyKeyColorName takes the source animation name, target animation name, the frame index, and the key binding to update. The target animation will set the color from the source animation.

image_47

In the image below, an array of keys are set to the colors from a source animation. Another array of keys is set to a specific linear color. All the animation frames are copied or assigned for a set of keys by calling the AllFrames method.

image_48

Tutorials

Razer Chroma Playlist

Import Runtime and Editor Modules

Import Animation From Unity

Play Composite Animations From Content Folder

Usage

1 Copy ChromaSDKPlugin to the ProjectFolder\Plugins\ChromaSDKPlugin folder

2 Open the Plugins Browser tab using the Edit->Plugins menu item

image_5

3 Make sure the ChromeSDKPlugin is enabled

image_6

Assets

In the Content Browser under the Add New->Miscellaneous menu item is where animation assets can be created for ChromaSDKPluginAnimation1DObject and ChromaSDKPluginAnimation2DObject.

image_33

Hovering ChromaSDK Animations will show a Play or Stop thumbnail. Clicking the Play thumbnail will play the animation effect when in play-mode or edit-mode.

image_34

Right-click a ChromaSDK Animation and select Edit to open the custom details view.

image_35

The details view sets the device type and allows the color animation frames to be edited. 1D animations support ChromaLink, Headset, and Mousepad devices. 2D animations support Keyboard, Keypad, and Mouse devices. The device preview shows a grid and clicking the elements will set the color from the color wheel. The Curve adjusts the timings for each animation frame.

image_36

ChromaSDK Animation objects can be referenced from blueprints. Create a variable of object type ChromaSDKPluginAnimation1DObject or ChromaSDKPluginAnimation2DObject. Use the variable SET so the animation asset can be selected from the dropdown.

image_37

Use Load on the animation before it can be used. Use IsLoaded to check if the animation has been loaded.

image_40

After the ChromaSDK Animation has been loaded and set in a variable, it can be played.

image_38

A playing ChromaSDK Animation can be stopped.

image_39

Use Unload to unload the animation. ChromaSDKPluginBPLibrary::UnInit will automatically unload animations.

image_41

Blueprint objects

FChromaSDKEffectResult

FChromaSDKEffectResult holds a ChromaSDK result and an effect identifier.

image_12

struct FChromaSDKEffectResult
{
	UPROPERTY(BlueprintReadOnly)
	int Result;

	UPROPERTY(BlueprintReadOnly)
	FChromaSDKGuid EffectId;
}

EChromaSDKDeviceEnum

EChromaSDKDeviceEnum is a list of all ChromaSDK devices.

image_13

enum class EChromaSDKDeviceEnum : uint8
{
	DE_ChromaLink           UMETA(DisplayName = "ChromaLink"),
	DE_Headset		UMETA(DisplayName = "Headset"),
	DE_Keyboard		UMETA(DisplayName = "Keyboard"),
	DE_Keypad		UMETA(DisplayName = "Keypad"),
	DE_Mouse		UMETA(DisplayName = "Mouse"),
	DE_Mousepad		UMETA(DisplayName = "Mousepad")
};

EChromaSDKDevice1DEnum

EChromaSDKDevice1DEnum is a device that uses a one-dimensional array for custom effects.

image_14

enum class EChromaSDKDevice1DEnum : uint8
{
	DE_ChromaLink	        UMETA(DisplayName = "ChromaLink"),
	DE_Headset		UMETA(DisplayName = "Headset"),
	DE_Mousepad		UMETA(DisplayName = "Mousepad")
};

EChromaSDKDevice2DEnum

EChromaSDKDevice2DEnum is a device that uses a two-dimensional array for custom effects.

image_15

enum class EChromaSDKDevice2DEnum : uint8
{
	DE_Keyboard		UMETA(DisplayName = "Keyboard"),
	DE_Keypad		UMETA(DisplayName = "Keypad"),
	DE_Mouse		UMETA(DisplayName = "Mouse"),
};

FChromaSDKColors

FChromaSDKColors holds an array of colors.

image_16

struct FChromaSDKColors
{
	UPROPERTY(BlueprintReadOnly)
	TArray<FLinearColor> Colors;
};

EChromaSDKKeyboardKey

EChromaSDKKeyboardKey represents a key on the keyboard.

image_30

enum class EChromaSDKKeyboardKey : uint8
{
	KK_ESC                           UMETA(DisplayName = "Esc (VK_ESCAPE)"),
	KK_F1                            UMETA(DisplayName = "F1 (VK_F1)"),
	...
	KK_KOR_7                         UMETA(DisplayName = "(0xFF)"),
	KK_INVALID                       UMETA(DisplayName = "Invalid keys.")
};

EChromaSDKMouseLed

EChromaSDKMouseLed represents an led on the mouse

image_31

enum class EChromaSDKMouseLed : uint8
{
	ML_SCROLLWHEEL		UMETA(DisplayName = "Scroll Wheel LED"),
	ML_LOGO			UMETA(DisplayName = "Logo LED"),
	...
	ML_RIGHT_SIDE6		UMETA(DisplayName = "Right LED 6"),
	ML_RIGHT_SIDE7		UMETA(DisplayName = "Right LED 7")
};

Blueprint functions

ChromaSDKPlugin BP Library

  1. bool UChromaSDKPluginBPLibrary::IsPlatformWindows()

    • Returns true if the platform is windows. Although this call works on all platforms, all the remaining BP methods only work on the Windows platform
  2. int UChromaSDKPluginBPLibrary::ChromaSDKInit()

    • Returns the result of calling ChromaSDK::Init(). Initializes the ChromaSDK.
  3. int UChromaSDKPluginBPLibrary::ChromaSDKUnInit()

    • Returns the result of calling ChromaSDK::UnInit. Uninitializes the ChromaSDK.
  4. FChromaSDKEffectResult UChromaSDKPluginBPLibrary::ChromaSDKCreateEffectNone(const EChromaSDKDeviceEnum& device)

    • Returns the FChromaSDKEffectResult after creating a CHROMA_NONE effect given the device. This effect clears the lighting effect for a device.
  5. FChromaSDKEffectResult UChromaSDKPluginBPLibrary::ChromaSDKCreateEffectStatic(const EChromaSDKDeviceEnum& device, const FLinearColor& color)

    • Returns the FChromaSDKEffectResult after creating a CHROMA_STATIC effect given the device and color. This effect sets the lighting effect to a static color for a device.
  6. FChromaSDKEffectResult UChromaSDKPluginBPLibrary::ChromaSDKCreateEffectCustom1D(const EChromaSDKDevice1DEnum& device, const TArray<FLinearColor>& colors)

    • Returns the FChromaSDKEffectResult after creating a CHROMA_CUSTOM effect given the device and one-dimensional color array. This effect sets the lighting effect with an array of colors for a device.
  7. FChromaSDKEffectResult UChromaSDKPluginBPLibrary::ChromaSDKCreateEffectCustom2D(const EChromaSDKDevice2DEnum& device, const TArray<FChromaSDKColors>& colors)

    • Returns the FChromaSDKEffectResult after creating a (CHROMA_CUSTOM or CHROMA_CUSTOM2) effect given the device and two-dimensional color array. This effect sets the lighting effect with an array of colors for a device.
  8. int UChromaSDKPluginBPLibrary::ChromaSDKSetEffect(const FChromaSDKGuid& effectId)

    • Returns the result of calling ChromaSDK::SetEffect given the effect identifier. Activates the given effect.
  9. int UChromaSDKPluginBPLibrary::ChromaSDKDeleteEffect(const FChromaSDKGuid& effectId)

    • Returns the result of calling ChromaSDK::DeleteEffect given the effect identifier. Deletes the given effect.
  10. TArray<FLinearColor> CreateColors1D(const EChromaSDKDevice1DEnum& device)

    • Returns a blank one-dimensional color array given the device.
  11. TArray<FChromaSDKColors> CreateColors2D(const EChromaSDKDevice2DEnum& device)

    • Returns a blank two-dimensional color array given the device.
  12. TArray<FLinearColor> CreateRandomColors1D(const EChromaSDKDevice1DEnum& device)

    • Returns a one-dimensional random color array given the device.
  13. TArray<FChromaSDKColors> CreateRandomColors2D(const EChromaSDKDevice2DEnum& device)

    • Returns a two-dimensional random color array given the device.
  14. const TArray<FChromaSDKColors>& SetKeyboardKeyColor(const EChromaSDKKeyboardKey& key, const FLinearColor& color, TArray<FChromaSDKColors>& colors)

    • Returns a modified two-dimensional color array with the key color changed.
  15. const TArray<FChromaSDKColors>& SetMouseLedColor(const EChromaSDKMouseLed& led, const FLinearColor& color, TArray<FChromaSDKColors>& colors)

    • Returns a modified two-dimensional color array with the led color changed.

Examples

Example Level

The Example Level displays a UI Blueprint Widget with buttons that have onclick events that use the ChromaSDKPlugin.

1 Open the level in Content/Levels/ExampleLevel

image_1

2 Open the UI Blueprint Widget in Content/Blueprints/ExampleWidget_BP

image_2

3 Open the Level Blueprint with the Blueprints->Open Level Blueprint menu item

image_3

4 The main features of the example level will be labelled with comment blocks

image_4

The example begins at Event BeginPlay which is executed on launch. The Setup UI custom event loads the Blueprint Widget. If the Windows platform is detected, the ChromaSDKInit custom event is called.

image_7

The SetupUI custom event loads the UI Blueprint Widget and saves a widget variable to be referenced by later UI controls. The Blueprint Widget is added to the viewport and then the SetupUIButtons custom event is called.

image_8

The SetupUIButtons custom event uses the widget variable to access the named buttons to bind onclicked events. When a button is clicked the Event delegate is invoked. Since the Event delegate doesn't take parameters, an unnamed custom event is used to prepare the button parameters and invoke the SetAllDeviceStaticColor custom event. FLinearColor is used to mimize the number of steps when passing colors to events and the SDK. This same setup is used for all the static color buttons.

image_9

The SetupUIButtons custom event calls other custom events to setup the clear button, the random button, and the animation buttons.

image_10

The example ends at Event EndPlay which executes when the game exits or ESC is pressed in the editor. If the Windows platform is detected, the ChromaSDKUninit custom event is called.

image_11

Getting Started

Note: ChromaSDKPlugin calls should be made on the Windows platform.

DebugPrintResult is an example custom event to check for result codes and print a message. The custom event takes parameters to include in the print message. A result code of zero is commonly used in the API to mean success. A success message is printed if detected. If an error message is printed if the result code is not zero.

image_19

Init

int UChromaSDKPluginBPLibrary::ChromaSDKInit()

Init returns the result of calling ChromaSDK::Init(). Initializes the ChromaSDK. A result of zero indicates success. Upon success, effects can be created, set, and deleted.

image_17

UnInit

int UChromaSDKPluginBPLibrary::ChromaSDKUnInit()

UnInit returns the result of calling ChromaSDK::UnInit. Uninitializes the ChromaSDK. A result of zero indicates success.

image_18

CreateEffectNone

FChromaSDKEffectResult UChromaSDKPluginBPLibrary::ChromaSDKCreateEffectNone(const EChromaSDKDeviceEnum& device)

CreateEffectNone returns the FChromaSDKEffectResult after creating a CHROMA_NONE effect given the device. This effect clears the lighting effect for a device. A result of zero indicates success.

image_20

After effects are created, this example shows expanding the result to check the result for success. The effect identifier can be used to activate the effect with SetEffect or delete the effect with DeleteEffect.

image_21

After an effect has been set, check the result for success. Either success or failure, the effect identifier can be deleted with DeleteEffect.

image_22

After an effect has been deleted, check the result for success. After effects have been created they can be used and then deleted or kept around to be reused. Be sure to delete effect identifiers before exiting for proper cleanup.

image_23

CreateEffectStatic

FChromaSDKEffectResult UChromaSDKPluginBPLibrary::ChromaSDKCreateEffectStatic(const EChromaSDKDeviceEnum& device, const FLinearColor& color)

CreateEffectStatic returns the FChromaSDKEffectResult after creating a CHROMA_STATIC effect given the device and color. This effect sets the lighting effect to a static color for a device.

image_24

CreateEffectCustom1D

FChromaSDKEffectResult UChromaSDKPluginBPLibrary::ChromaSDKCreateEffectCustom1D(const EChromaSDKDevice1DEnum& device, const TArray<FLinearColor>& colors)

CreateEffectCustom1D returns the FChromaSDKEffectResult after creating a CHROMA_CUSTOM effect given the device and one-dimensional color array. This effect sets the lighting effect with an array of colors for a device.

image_25

CreateEffectCustom2D

FChromaSDKEffectResult UChromaSDKPluginBPLibrary::ChromaSDKCreateEffectCustom2D(const EChromaSDKDevice2DEnum& device, const TArray<FChromaSDKColors>& colors)

CreateEffectCustom2D returns the FChromaSDKEffectResult after creating a (CHROMA_CUSTOM or CHROMA_CUSTOM2) effect given the device and two-dimensional color array. This effect sets the lighting effect with an array of colors for a device.

image_26

SetEffect

int UChromaSDKPluginBPLibrary::ChromaSDKSetEffect(const FChromaSDKGuid& effectId)

SetEffect returns the result of calling ChromaSDK::SetEffect given the effect identifier. Activates the given effect.

image_21

DeleteEffect

int UChromaSDKPluginBPLibrary::ChromaSDKDeleteEffect(const FChromaSDKGuid& effectId)

DeleteEffect returns the result of calling ChromaSDK::DeleteEffect given the effect identifier. Deletes the given effect.

image_22

CreateColors1D

TArray<FLinearColor> CreateColors1D(const EChromaSDKDevice1DEnum& device)

CreateColors1D returns a blank one-dimensional color array given the device.

image_28

CreateColors2D

TArray<FChromaSDKColors> CreateColors2D(const EChromaSDKDevice2DEnum& device)

CreateColors2D returns a blank two-dimensional color array given the device.

image_29

CreateRandomColors1D

TArray<FLinearColor> CreateRandomColors1D(const EChromaSDKDevice1DEnum& device)

CreateRandomColors1D returns a one-dimensional random color array given the device.

image_25

CreateRandomColors2D

TArray<FChromaSDKColors> CreateRandomColors2D(const EChromaSDKDevice2DEnum& device)

CreateRandomColors2D returns a two-dimensional random color array given the device.

image_26

SetKeyboardKeyColor

const TArray<FChromaSDKColors>& SetKeyboardKeyColor(const EChromaSDKKeyboardKey& key, const FLinearColor& color, TArray<FChromaSDKColors>& colors)

SetKeyboardKeyColor returns a modified two-dimensional color array with the key color changed.

image_27

SetMouseLedColor

const TArray<FChromaSDKColors>& SetMouseLedColor(const EChromaSDKMouseLed& led, const FLinearColor& color, TArray<FChromaSDKColors>& colors)

MouseLedColor returns a modified two-dimensional color array with the led color changed.

image_32