-
Notifications
You must be signed in to change notification settings - Fork 72
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #286 from DarthAffe/ReadMe
ReadMe
- Loading branch information
Showing
43 changed files
with
461 additions
and
427 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,30 +1,87 @@ | ||
| # RGB.NET | ||
| [](https://github.com/DarthAffe/RGB.NET/releases) | ||
| [](https://www.nuget.org/packages?q=rgb.net) | ||
| [](https://github.com/DarthAffe/RGB.NET/blob/master/LICENSE) | ||
| [](https://github.com/DarthAffe/RGB.NET/stargazers) | ||
| [](https://discord.gg/9kytURv) | ||
|
|
||
| This project aims to unify the use of various RGB-devices. | ||
| **It is currently under heavy development and will have breaking changes in the future!** Right now a lot of devices aren't working as expected and there are bugs/unfinished features. Please think about that when you consider using the library in this early stage. | ||
|
|
||
| If you want to help with layouting/testing devices or if you need support using the library feel free to join the [RGB.NET discord-channel](https://discord.gg/9kytURv). | ||
| > **IMPORTANT NOTE** | ||
| This is a library to integrate RGB-devices into your own application. It does not contain any executables! | ||
| If you're looking for a full blown software solution to manage your RGB-devices, take a look at [Artemis](https://artemis-rgb.com/). | ||
|
|
||
| ## Getting Started | ||
| ### Setup | ||
| 1. Add the [RGB.NET.Core](https://www.nuget.org/packages/RGB.NET.Core) and [Devices](https://www.nuget.org/packages?q=rgb.net.Devices)-Nugets for all devices you want to use. | ||
| 2. For some of the vendors SDK-libraries are needed. Check the contained Readmes for more information in that case. | ||
| 3. Create a new `RGBSurface`. | ||
| ```csharp | ||
| RGBSurface surface = new RGBSurface(); | ||
| ``` | ||
|
|
||
| ## Adding prerelease packages using NuGet ## | ||
| This is the easiest and therefore preferred way to include RGB.NET in your project. | ||
| 4. Initialize the providers for all devices you want to use and add the devices to the surface. For example: | ||
| ```csharp | ||
| CorsairDeviceProvider.Instance.Initialize(throwExceptions: true); | ||
| surface.Attach(CorsairDeviceProvider.Instance.Devices); | ||
| ``` | ||
| The `Initialize`-method allows to load only devices of specific types by setting a filter and for debugging purposes allows to enable exception throwing. (By default they are catched and provided through the `Exception`-event.) | ||
| You can also use the `Load`-Extension on the surface. | ||
| ```csharp | ||
| surface.Load(CorsairDeviceProvider.Instance); | ||
| ``` | ||
| > While most device-providers are implemented in a way that supports fast loading like this some may have a different loading procedures. (For example the `WS281XDeviceProvider` requires device-definitions before loading.) | ||
| Since there aren't any release-packages right now you'll have to use the CI-feed from [http://nuget.arge.be](http://nuget.arge.be). | ||
| You can include it either by adding ```http://nuget.arge.be/v3/index.json``` to your Visual Studio package sources or by adding this [NuGet.Config](https://github.com/DarthAffe/RGB.NET/tree/master/Documentation/NuGet.Config) to your project (at the same level as your solution). | ||
| 5. Add an update-trigger. In most cases the TimerUpdateTrigger is preferable, but you can also implement your own to fit your needs. | ||
| ```csharp | ||
| surface.RegisterUpdateTrigger(new TimerUpdateTrigger()); | ||
| ``` | ||
| > If you want to trigger updates manually the `ManualUpdateTrigger` should be used. | ||
| ### .NET 4.5 Support ### | ||
| At the end of the year with the release of .NET 5 the support for old .NET-Framwork versions will be droppped! | ||
| It's not recommended to use RGB.NET in projects targeting .NET 4.x that aren't planned to be moved to Core/.NET 5 in the future. | ||
| 6. *This step is optional but recommended.* For rendering the location of each LED on the surface can be important. Since not all SDKs provide useful layout-information you might want to add Layouts to your devices. (TODO: add wiki article for this) | ||
| Same goes for the location of the device on the surface. If you don't care about the exact location of the devices you can use: | ||
| ```csharp | ||
| surface.AlignDevices(); | ||
| ``` | ||
|
|
||
| The basic setup is now complete and you can start setting up your rendering. | ||
|
|
||
| ### Device-Layouts | ||
| To be able to have devices with correct LED-locations and sizes they need to be layouted. Pre-created layouts can be found at https://github.com/DarthAffe/RGB.NET-Resources. | ||
| ### Basic Rendering | ||
| As an example we'll add a moving rainbow over all devices on the surface. | ||
| 1. Create a led-group containing all leds on the surface (all devices) | ||
| ```csharp | ||
| ILedGroup allLeds = new ListLedGroup(surface, surface.Leds); | ||
| ``` | ||
|
|
||
| If you plan to create layouts for your own devices check out https://github.com/DarthAffe/RGB.NET/wiki/Creating-Layouts first. There's also a layout-editor which strongly simplifies most of the work: https://github.com/SpoinkyNL/RGB.NET-Layout-Editor | ||
| 2. Create a rainbow-gradient. | ||
| ```csharp | ||
| RainbowGradient rainbow = new RainbowGradient(); | ||
| ``` | ||
|
|
||
| ### Example usage of RGB.NET | ||
| [](http://www.youtube.com/watch?v=JLRa0Wv4qso) | ||
| 3. Add a decorator to the gradient to make it move. (Decorators are | ||
| ```csharp | ||
| rainbow.AddDecorator(new MoveGradientDecorator(surface)); | ||
| ``` | ||
|
|
||
| #### Example Projects | ||
| [https://github.com/DarthAffe/KeyboardAudioVisualizer](https://github.com/DarthAffe/KeyboardAudioVisualizer) | ||
| [https://github.com/DarthAffe/RGBSyncPlus](https://github.com/DarthAffe/RGBSyncPlus) | ||
| 4. Create a texture (the size - in this example 10, 10 - is not important here since the gradient shoukd be stretched anyway) | ||
| ```csharp | ||
| ITexture texture = new ConicalGradientTexture(new Size(10, 10), rainbow); | ||
| ``` | ||
|
|
||
| 5. Add a brush rendering the texture to the led-group | ||
| ```csharp | ||
| allLeds.Brush = new TextureBrush(texture); | ||
| ``` | ||
|
|
||
| ### Full example | ||
| ```csharp | ||
| RGBSurface surface = new RGBSurface(); | ||
| surface.Load(CorsairDeviceProvider.Instance); | ||
| surface.AlignDevices(); | ||
|
|
||
| surface.RegisterUpdateTrigger(new TimerUpdateTrigger()); | ||
|
|
||
| ILedGroup allLeds = new ListLedGroup(surface, surface.Leds); | ||
| RainbowGradient rainbow = new RainbowGradient(); | ||
| rainbow.AddDecorator(new MoveGradientDecorator(surface)); | ||
| ITexture texture = new ConicalGradientTexture(new Size(10, 10), rainbow); | ||
| allLeds.Brush = new TextureBrush(texture); | ||
| ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,36 @@ | ||
| [RGB.NET](https://github.com/DarthAffe/RGB.NET) Core-Package. | ||
|
|
||
| Required to use RGB.NET | ||
|
|
||
| ## Getting Started | ||
| ```csharp | ||
| // Create a surface - this is where all devices belongs too | ||
| RGBSurface surface = new RGBSurface(); | ||
|
|
||
| // Load your devices - check out the RGB.NET.Devices-packages for more information | ||
| // TODO: Load device-providers | ||
| // Automatically align devices to not overlap - you can ofc also move them by hand | ||
| surface.AlignDevices(); | ||
|
|
||
| // Register an update-trigger | ||
| surface.RegisterUpdateTrigger(new TimerUpdateTrigger()); | ||
| ``` | ||
|
|
||
| ## Basis Rendering | ||
| ```csharp | ||
| // Create a led-group containing all leds on the surface | ||
| ILedGroup allLeds = new ListLedGroup(surface, surface.Leds); | ||
|
|
||
| // Create a rainbow gradient | ||
| RainbowGradient rainbow = new RainbowGradient(); | ||
|
|
||
| // Animate the gradient to steadily move | ||
| rainbow.AddDecorator(new MoveGradientDecorator(surface)); | ||
|
|
||
| // Create a texture rendering that gradient | ||
| ITexture texture = new ConicalGradientTexture(new Size(10, 10), rainbow); | ||
|
|
||
| // Create a brush rendering the texture and assign it to the group | ||
| allLeds.Brush = new TextureBrush(texture); | ||
| ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,13 @@ | ||
| [RGB.NET](https://github.com/DarthAffe/RGB.NET) Device-Provider-Package for Asus-Devices. | ||
|
|
||
| ## Usage | ||
| This provider follows the default pattern and does not require additional setup. | ||
|
|
||
| ```csharp | ||
| surface.Load(AsusDeviceProvider.Instance); | ||
| ``` | ||
|
|
||
| # Required SDK | ||
| This providers requires the `Interop.AuraServiceLib.dll` to be present on the system. Normally this dll is installed with ASUS Aura and registered in the GAC. | ||
| There are some known issue with this dll missing and it's recommended to pack it with your application. You can get it from your Aura-Installation or get a copy from [https://redist.arge.be/Asus/Interop.AuraServiceLib.dll](https://redist.arge.be/Asus/Interop.AuraServiceLib.dll). | ||
| If packed it has to be located in a spot that your application is loading runtime dlls from. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,24 @@ | ||
| [RGB.NET](https://github.com/DarthAffe/RGB.NET) Device-Provider-Package for Cooler Master-Devices. | ||
|
|
||
| ## Usage | ||
| This provider follows the default pattern and does not require additional setup. | ||
|
|
||
| ```csharp | ||
| surface.Load(CoolerMasterDeviceProvider.Instance); | ||
| ``` | ||
|
|
||
| # Required SDK | ||
| This providers requires native SDK-dlls. | ||
| You can get them directly from Cooler Master at [https://templates.coolermaster.com/](https://templates.coolermaster.com/) (Direct Link: [https://templates.coolermaster.com/assets/sdk/coolermaster-sdk.zip](https://templates.coolermaster.com/assets/sdk/coolermaster-sdk.zip)) | ||
|
|
||
| Since the SDK-dlls are native it's important to use the correct architecture you're building your application for. (If in doubt you can always include both.) | ||
|
|
||
| ### x64 | ||
| `Src\SDK\x64\SDKDLL.dll` from the SDK-zip needs to be distributed as `<application-directory>\x64\CMSDK.dll` | ||
|
|
||
| You can use other, custom paths by adding them to `CoolerMasterDeviceProvider.PossibleX64NativePaths`. | ||
|
|
||
| ### x86 | ||
| `Src\SDK\x86\SDKDLL.dll` from the SDK-zip needs to be distributed as `<application-directory>\x86\CMSDK.dll` | ||
|
|
||
| You can use other, custom paths by adding them to `CoolerMasterDeviceProvider.PossibleX86NativePaths`. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,24 @@ | ||
| [RGB.NET](https://github.com/DarthAffe/RGB.NET) Device-Provider-Package for Corsair-Devices. | ||
|
|
||
| ## Usage | ||
| This provider follows the default pattern and does not require additional setup. | ||
|
|
||
| ```csharp | ||
| surface.Load(CorsairDeviceProvider.Instance); | ||
| ``` | ||
|
|
||
| # Required SDK | ||
| This providers requires native SDK-dlls. | ||
| You can get them directly from Corsair at [https://github.com/CorsairOfficial/cue-sdk/releases](https://github.com/CorsairOfficial/cue-sdk/releases) | ||
|
|
||
| Since the SDK-dlls are native it's important to use the correct architecture you're building your application for. (If in doubt you can always include both.) | ||
|
|
||
| ### x64 | ||
| `redist\x64\CUESDK.x64_2019.dll` from the SDK-zip needs to be distributed as `<application-directory>\x64\CUESDK.x64_2019.dll` (or simply named `CUESDK.dll`) | ||
|
|
||
| You can use other, custom paths by adding them to `CorsairDeviceProvider.PossibleX64NativePaths`. | ||
|
|
||
| ### x86 | ||
| `redist\i386\CUESDK_2019.dll` from the SDK-zip needs to be distributed as `<application-directory>\x86\CUESDK_2019.dll` (or simply named `CUESDK.dll`) | ||
|
|
||
| You can use other, custom paths by adding them to `CorsairDeviceProvider.PossibleX86NativePaths`. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,16 @@ | ||
| [RGB.NET](https://github.com/DarthAffe/RGB.NET) Device-Provider-Package for E1.31 DMX-Devices. | ||
|
|
||
| ## Usage | ||
| This provider does not load anything by default and requires additional configuration to work. | ||
|
|
||
| ```csharp | ||
| // Add as many DMX devices as you like | ||
| DMXDeviceProvider.Instance.AddDeviceDefinition(new E131DMXDeviceDefinition("<hostname>")); | ||
|
|
||
| surface.Load(DMXDeviceProvider.Instance); | ||
| ``` | ||
|
|
||
| You can also configure additional things like device names, custom ports, heartbeats and so on in the DeviceDefinition. | ||
|
|
||
| # Required SDK | ||
| This provider does not require an additional SDK. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,16 @@ | ||
| [RGB.NET](https://github.com/DarthAffe/RGB.NET) Device-Provider-Package for Debug-Devices. | ||
|
|
||
| > This provider is only for debug purposes! | ||
| ## Usage | ||
| This provider does not load anything by default and requires additional configuration to work. | ||
|
|
||
| ```csharp | ||
| // Add as many debug devices as you like | ||
| DebugDeviceProvider.Instance.AddFakeDeviceDefinition(DeviceLayout.Load("<Path to layout-file>")); | ||
|
|
||
| surface.Load(DebugDeviceProvider.Instance); | ||
| ``` | ||
|
|
||
| # Required SDK | ||
| This provider does not require an additional SDK. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,27 @@ | ||
| [RGB.NET](https://github.com/DarthAffe/RGB.NET) Device-Provider-Package for Logitech-Devices. | ||
|
|
||
| ## Usage | ||
| This provider follows the default pattern and does not require additional setup. | ||
|
|
||
| ```csharp | ||
| surface.Load(LogitechDeviceProvider.Instance); | ||
| ``` | ||
|
|
||
| Since the logitech SDK does not provide device information only known devices will work. | ||
| You can add detection for additional devices by adding entires for them to the respective static `DeviceDefinitions` on the `LogitechDeviceProvider`. | ||
|
|
||
| # Required SDK | ||
| This providers requires native SDK-dlls. | ||
| You can get them directly from Logitech at [https://www.logitechg.com/en-us/innovation/developer-lab.html](https://www.logitechg.com/en-us/innovation/developer-lab.html) (Direct Link: [https://www.logitechg.com/sdk/LED_SDK_9.00.zip](https://www.logitechg.com/sdk/LED_SDK_9.00.zip)) | ||
|
|
||
| Since the SDK-dlls are native it's important to use the correct architecture you're building your application for. (If in doubt you can always include both.) | ||
|
|
||
| ### x64 | ||
| `Lib\LogitechLedEnginesWrapper\x64\LogitechLedEnginesWrapper.dll` from the SDK-zip needs to be distributed as `<application-directory>\x64\LogitechLedEnginesWrapper.dll` | ||
|
|
||
| You can use other, custom paths by adding them to `LogitechDeviceProvider.PossibleX64NativePaths`. | ||
|
|
||
| ### x86 | ||
| `Lib\LogitechLedEnginesWrapper\x86\LogitechLedEnginesWrapper.dll` from the SDK-zip needs to be distributed as `<application-directory>\x86\LogitechLedEnginesWrapper.dll` | ||
|
|
||
| You can use other, custom paths by adding them to `LogitechDeviceProvider.PossibleX86NativePaths`. |
Oops, something went wrong.