add support for OSC blob

README.md

@@ -4,8 +4,7 @@ UE4-OSC
 OSC plugin for Unreal Engine 4 to send and receive OSC messages with blueprints!
 
 
-Tutorial
-========
+# Tutorial
 
 Dannington made a super tutorial!
 
@@ -14,13 +13,12 @@ Watch it to properly install the plugin and get some brilliant ideas on how to u
 https://www.youtube.com/watch?v=GGGs-n-CKtY
 
 
-Also, go to the UE4 forum:
+Also, go to the UE4 forum dedicated thread:
 
 https://forums.unrealengine.com/showthread.php?49627-Plugin-OSC-for-UE4
 
 
-Integration
-===========
+# Integration
 
 Install Visual Studio 2015 on Windows (Community edition works) or XCode on MaxOSX.
 
@@ -34,41 +32,68 @@ Run the "*.uproject" file: the plugin is compiled automatically.
 Alternatively, right-clic the "*.uproject" to generate Visual Studio or XCode project files.
 
 
-Usage
-=====
+# Usage
 
- - Receiver:
- 
-Set the listening port in the plugin settings.
+### Receiver
+
+Set the listening port as "Receive From" in the plugin settings. (Edit/Project Settings/Plugins/OSC)
 
 Add a OscReceiverComponent to your Blueprint class and bind the OnOscReceived custom event, or
+subclass the OscReceiverActor and bind the OnOscReceived custom event.
 
-Subclass the OscReceiverActor and bind the OnOscReceived custom event.
+The OnOscReceived event gives: the OSC address, the OSC parameters and the IP of the sender.
 
-Use the PopFloat/Int/Bool/String functions, or standard array functions, to retrieve the OSC message parameters.
+The OSC parameters is an array of OSC elements. To read the content, either:
+ - chain PopFloat/Int/Bool/String/Blob functions to get the first value, or
+ - use the standard GET function and AsFloat/Int/Bool/String/Blob functions to cast the element to its value. This is slightly more efficient.
 
+### Sender
 
- - Sender:
- 
-Set the "send to" addresses in the plugin settings.
+Set the "Send Targets" addresses in the plugin settings. (Edit/Project Settings/Plugins/OSC)
 
-Use the PushFloat/Int/Bool/String functions, or standard array functions, to build the OSC message parameters.
+You can also add new targets dynamically, using the "Add Send Osc Target" function.
+It is especially useful for "ping"-like behavior.
 
-Use the SendOsc function to send the OSC message
+Send a single message with "Send Osc" or a bundle of messages with "Send Osc Bundle".
 
-Use the SendOscBundle function to send an OSC bundle (array of messages)
+The "Send Osc" function takes: the OSC address, the OSC parameters and the "target index" of the destination.
 
+Build the OSC parameters for a message:
+ - chain PushFloat/Int/Bool/String/Blob functions, or
+ - fill an array of "Osc Data Elem" with the standard array functions and the FromFloat/Int/Bool/String/Blob functions.
+
+The "target index" refers to an index in the "Send Targets" array in the settings,
+or to the result of the "Add Send Osc Target" function.
+
+### Inputs (experimental)
 
- - Inputs:
- 
 List the messages that should be UE4 inputs (like a game controller). A new input is created for each message.
 
 Bind OSC inputs to UE4 action in the usual "Input" project settings.
 
 
-Engine version
-=====
+# General information
+
+### Troubleshooting
+
+The plugin uses the standard UE4 logging system.
+
+Check your logs (Window/Developers Tools/Output Log) before asking for help!
+
+### String limitation
+
+Historically, the plugin handles OSC string using "FName". Unfortunately, the length of
+a "FName" is limited to 1024 characters. So this plugin does not handle long strings correctly.
+
+If you need long strings, prefer using blobs.
+
+### Blob
+
+The OSC protocol supports buffers as "blob".
+
+This plugin implements them as "Array<uint8>". It plays nicely with the "Extended Standard Library" plugin by "Low Entry".
+
+
+# Engine version
 
 Get the right branch for your engine version: "master" for the latest version, "before4.8" for 4.4, ..., 4.7, etc.
-
-Optionally, set the OSC_ENGINE_VERSION value (in Source/OSC/Private/Osc.h) to compile for a specific engine version.