Re-add examples

CMakeLists.txt

@@ -13,6 +13,7 @@ endif()
 option(LSL_UNIXFOLDERS "Use the unix folder layout for install targets" On)
 option(LSL_NO_FANCY_LIBNAME "Skip library name decorations (32/64/-debug)")
 option(LSL_LEGACY_CPP_ABI "Build legacy C++ ABI" OFF)
+option(LSL_BUILD_EXAMPLES "Build example programs in examples/" OFF)
 
 # lsl uses boost, but several other projects (e.g. Matlab) also use boost.
 # To prevent clashes with different boost versions, lsl ships a subset of
@@ -219,4 +220,8 @@ if(LSL_UNITTESTS)
 	add_subdirectory(testing)
 endif()
 
+if(LSL_BUILD_EXAMPLES)
+	add_subdirectory(examples)
+endif()
+
 LSLGenerateCPackConfig()

examples/CMakeLists.txt

@@ -0,0 +1,40 @@
+cmake_minimum_required(VERSION 3.5)
+project(Examples
+	LANGUAGES C CXX
+	VERSION 0.2.0)
+
+# convenience function to add an example file
+# this creates a target, links the necessary libraries and
+# creates an install target
+function(addlslexample name extension)
+	add_executable(${name}
+		${name}.${extension}
+	)
+	target_link_libraries(${name} PRIVATE LSL::lsl)
+	target_compile_features(${name} PRIVATE cxx_constexpr)
+	installLSLApp(${name})
+endfunction()
+
+find_package(Threads)
+
+addlslexample(GetAllStreams cpp)
+addlslexample(GetFullinfo cpp)
+addlslexample(GetTimeCorrection cpp)
+addlslexample(HandleMetaData cpp)
+addlslexample(HandleMetaDataC c)
+addlslexample(ReceiveData cpp)
+addlslexample(ReceiveDataC c)
+addlslexample(ReceiveDataInChunks cpp)
+addlslexample(ReceiveDataSimple cpp)
+addlslexample(ReceiveStringMarkers cpp)
+addlslexample(ReceiveStringMarkersC c)
+addlslexample(SendDataC c)
+addlslexample(SendDataInChunks cpp)
+addlslexample(SendDataSimple cpp)
+addlslexample(SendMultipleStreams cpp)
+addlslexample(SendStringMarkers cpp)
+addlslexample(SendStringMarkersC c)
+addlslexample(TestSyncWithoutData cpp)
+
+target_link_libraries(TestSyncWithoutData PRIVATE Threads::Threads)
+

examples/GetAllStreams.cpp

@@ -0,0 +1,33 @@
+#include <iostream>
+#include <lsl_cpp.h>
+
+/**
+ * This example program shows how all streams that are currently present on the lab network can be
+ * resolved and displayed. This is useful for browsing applications.
+ */
+
+int main(int argc, char* argv[]) {
+	try {
+		std::cout << "Here is a one-shot resolve of all current streams:" << std::endl;
+
+		// discover all streams on the network
+		std::vector<lsl::stream_info> results = lsl::resolve_streams();
+
+		// display them
+		for (auto& stream: results) std::cout << stream.as_xml() << "\n\n";
+
+		std::cout << "Press any key to switch to the continuous resolver test: " << std::endl;
+		std::cin.get();
+
+		lsl::continuous_resolver r;
+		while (true) {
+			std::vector<lsl::stream_info> tmp = r.results();
+			for (auto& val : tmp) std::cout << val.name() << " ";
+			std::cout << std::endl;
+		}
+
+	} catch (std::exception& e) { std::cerr << "Got an exception: " << e.what() << std::endl; }
+	std::cout << "Press any key to exit. " << std::endl;
+	std::cin.get();
+	return 0;
+}

examples/GetFullinfo.cpp

@@ -0,0 +1,47 @@
+#include <iostream>
+#include <lsl_cpp.h>
+
+/**
+ * This example program demonstrates how the full version of the stream info (i.e. including the
+ * potentially large .desc() field) can be obtained from an inlet. Note that the output of the
+ * resolve functions only includes the core information otherwise.
+ */
+
+int main(int argc, char* argv[]) {
+	std::string field, value;
+	if (argc != 3) {
+		std::cout << "This connects to a stream which has a particular value for a given field and "
+		             "displays its full stream_info contentss."
+		          << std::endl;
+		std::cout << "Please enter a field name and the desired value (e.g. \"type EEG\" (without "
+		             "the quotes)):"
+		          << std::endl;
+		std::cin >> field >> value;
+	} else {
+		field = argv[1];
+		value = argv[2];
+	}
+
+	try {
+		// resolve the stream of interet
+		std::cout << "Now resolving streams..." << std::endl;
+		std::vector<lsl::stream_info> results = lsl::resolve_stream(field, value);
+
+		std::cout << "Here is what was resolved: " << std::endl;
+		std::cout << results[0].as_xml() << std::endl;
+
+		// make an inlet to get data from it
+		std::cout << "Now creating the inlet..." << std::endl;
+		lsl::stream_inlet inlet(results[0]);
+
+		// get & display the info
+		std::cout << "The information about this stream is displayed in the following: "
+		          << std::endl;
+		lsl::stream_info info = inlet.info();
+		std::cout << info.as_xml() << std::endl;
+
+	} catch (std::exception& e) { std::cerr << "Got an exception: " << e.what() << std::endl; }
+	std::cout << "Press any key to exit. " << std::endl;
+	std::cin.get();
+	return 0;
+}

examples/GetTimeCorrection.cpp

@@ -0,0 +1,51 @@
+#include <iostream>
+#include <lsl_cpp.h>
+
+/**
+ * This example demonstrates how a time-correction value can be obtained on demand for a particular
+ * stream on the net. This time-correction value, when added to the time stamp of an obtained
+ * sample, remaps the sample's time stamp into the local clock domain (so it is in the same domain
+ * as what lsl::local_clock() would return). For streams coming from the same computer, this value
+ * should be approx. 0 (up to some tolerance).
+ */
+
+int main(int argc, char* argv[]) {
+	std::string field, value;
+	if (argc != 3) {
+		std::cout << "This connects to a stream which has a particular value for a given field and "
+		             "gets the time-synchronization information for it."
+		          << std::endl;
+		std::cout << "Please enter a field name and the desired value (e.g. \"type EEG\" (without "
+		             "the quotes)):"
+		          << std::endl;
+		std::cin >> field >> value;
+	} else {
+		field = argv[1];
+		value = argv[2];
+	}
+
+	try {
+		// resolve the stream of interet
+		std::cout << "Now resolving streams..." << std::endl;
+		std::vector<lsl::stream_info> results = lsl::resolve_stream(field, value);
+
+		std::cout << "Here is what was resolved: " << std::endl;
+		std::cout << results[0].as_xml() << std::endl;
+
+		// make an inlet to get data from it
+		std::cout << "Now creating the inlet..." << std::endl;
+		lsl::stream_inlet inlet(results[0]);
+
+		// start receiving & displaying the data
+		std::cout << "Press [Enter] to query a new correction value (clocks may drift)..."
+		          << std::endl;
+		while (true) {
+			std::cout << inlet.time_correction() << std::endl;
+			std::cin.get();
+		}
+
+	} catch (std::exception& e) { std::cerr << "Got an exception: " << e.what() << std::endl; }
+	std::cout << "Press any key to exit. " << std::endl;
+	std::cin.get();
+	return 0;
+}

examples/HandleMetaData.cpp

@@ -0,0 +1,49 @@
+#include <iostream>
+#include <lsl_cpp.h>
+
+int main(int argc, char* argv[]) {
+	try {
+		// create a new stream_info and declare some meta-data (in accordance with XDF format)
+		const char* name = argc > 1 ? argv[1] : "MetaTester";
+		lsl::stream_info info(name, "EEG", 8, 100, lsl::cf_float32, "myuid323457");
+		lsl::xml_element chns = info.desc().append_child("channels");
+		const char* labels[] = {"C3", "C4", "Cz", "FPz", "POz", "CPz", "O1", "O2"};
+		for (const char* label : labels)
+			chns.append_child("channel")
+			    .append_child_value("label", label)
+			    .append_child_value("unit", "microvolts")
+			    .append_child_value("type", "EEG");
+		info.desc().append_child_value("manufacturer", "SCCN");
+		info.desc()
+		    .append_child("cap")
+		    .append_child_value("name", "EasyCap")
+		    .append_child_value("size", "54")
+		    .append_child_value("labelscheme", "10-20");
+
+		// create outlet for the stream
+		lsl::stream_outlet outlet(info);
+
+		// === the following could run on another computer ===
+
+		// resolve the stream and open an inlet
+		std::vector<lsl::stream_info> results = lsl::resolve_stream("name", name);
+		lsl::stream_inlet inlet(results[0]);
+
+		// get the full stream info (including custom meta-data) and dissect it
+		lsl::stream_info inf = inlet.info();
+		std::cout << "The stream's XML meta-data is: \n"
+		          << inf.as_xml()
+		          << "\nThe manufacturer is: " << inf.desc().child_value("manufacturer")
+		          << "\nThe cap circumference is: " << inf.desc().child("cap").child_value("size")
+		          << "\nThe channel labels are as follows:\n";
+		lsl::xml_element ch = inf.desc().child("channels").child("channel");
+		for (int k = 0; k < info.channel_count(); k++) {
+			std::cout << "  " << ch.child_value("label") << std::endl;
+			ch = ch.next_sibling();
+		}
+
+	} catch (std::exception& e) { std::cerr << "Got an exception: " << e.what() << std::endl; }
+	std::cout << "Press any key to exit. " << std::endl;
+	std::cin.get();
+	return 0;
+}

examples/HandleMetaDataC.c

@@ -0,0 +1,59 @@
+#include <lsl_c.h>
+#include <stdio.h>
+
+int main(int argc, char* argv[]) {
+	int c;							/* channel index */
+	lsl_xml_ptr desc,chns,chn,cap;	/* some xml element pointers */ 
+	lsl_outlet outlet;				/* stream outlet */
+	lsl_streaminfo info,inf;		/* streaminfo objects */
+	lsl_inlet inlet;				/* a stream inlet to get samples from */
+	int errcode;					/* error code (lsl_lost_error or timeouts) */
+	const char* labels[] = {"C3","C4","Cz","FPz","POz","CPz","O1","O2"};
+
+	/* create a new streaminfo and declare some meta-data (in accordance with XDF format) */
+	const char* name = argc > 1 ? argv[1] : "MetaTester";
+	info = lsl_create_streaminfo(name,"EEG",8,100,cft_float32,"myuid323457");
+	desc = lsl_get_desc(info);
+	chns = lsl_append_child(desc,"channels");
+	for (c=0;c<8;c++) {
+		chn = lsl_append_child(chns,"channel");
+		lsl_append_child_value(chn,"label",labels[c]);
+		lsl_append_child_value(chn,"unit","microvolts");
+		lsl_append_child_value(chn,"type","EEG");
+	}
+	lsl_append_child_value(desc,"manufacturer","SCCN");
+	cap = lsl_append_child(desc,"cap");
+    lsl_append_child_value(cap,"name","EasyCap");
+    lsl_append_child_value(cap,"size","54");
+    lsl_append_child_value(cap,"labelscheme","10-20");
+
+	/* create outlet for the stream */
+	outlet = lsl_create_outlet(info,0,360);
+
+	/*  === the following could run on another computer === */
+
+	/* resolve the stream and open an inlet */
+	lsl_resolve_byprop(&info,1,"name","MetaTester",1,LSL_FOREVER);
+	inlet = lsl_create_inlet(info, 360, LSL_NO_PREFERENCE, 1);
+	inf = lsl_get_fullinfo(inlet,LSL_FOREVER,&errcode);
+	printf("The stream's XML meta-data is: \n");
+	printf("%s\n",lsl_get_xml(inf)); 
+	printf("The manufacturer is: %s\n",lsl_child_value_n(lsl_get_desc(inf),"manufacturer"));
+	printf("The cap circumference is: %s\n",lsl_child_value_n(lsl_child(lsl_get_desc(inf),"cap"),"size"));
+	printf("The channel labels are as follows:\n");
+	chn = lsl_child(lsl_child(lsl_get_desc(inf),"channels"),"channel");
+    for (c=0; c<lsl_get_channel_count(inf); c++) {
+		printf("  %s\n",lsl_child_value_n(chn,"label"));
+        chn = lsl_next_sibling(chn);
+    }
+
+	/* destroy objects and free memory */
+	lsl_destroy_streaminfo(inf);
+	lsl_destroy_inlet(inlet);
+	lsl_destroy_outlet(outlet);
+	lsl_destroy_streaminfo(info);
+
+	/* wait for keypress */
+	getchar();
+	return 0;
+}

examples/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2018 Christian Kothe, Tristan Stenner
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.