Skip to content

Latest commit

 

History

History
315 lines (199 loc) · 12.1 KB

API_Reference.md

File metadata and controls

315 lines (199 loc) · 12.1 KB
Raw

ofxPubSubOsc API Reference

TOC

API

ofxSubscribeOsc

Reference type

  • template <typename T> void ofxSubscribeOsc(int port, const string &address, T &value);

Setter Function / Method

setter function

  • template <typename T, typename R> void ofxSubscribeOsc(int port, const string &address, R (*callback)(T &));

setter method

  • template <typename T, typename R, typename C> void ofxSubscribeOsc(int port, const string &address, C &that, R (C::*callback)(T));
  • template <typename T, typename R, typename C> void ofxSubscribeOsc(int port, const string &address, C *that, R (C::*callback)(T));

const setter method (if you don't change property)

  • template <typename T, typename R, typename C> void ofxSubscribeOsc(int port, const string &address, const C &that, R (C::*callback)(T) const);
  • template <typename T, typename R, typename C> void ofxSubscribeOsc(int port, const string &address, const C *that, R (C::*callback)(T) const);

Callback Function / Method receive ofxOscMessage

callback function

  • template <typename R> void ofxSubscribeOsc(int port, const string &address, R (*callback)(ofxOscMessage &));

callback method

  • template <typename C, typename R> void ofxSubscribeOsc(int port, const string &address, C &that, R (C::*callback)(ofxOscMessage &));
  • template <typename C, typename R> void ofxSubscribeOsc(int port, const string &address, C *that, R (C::*callback)(ofxOscMessage &));

const callback method

  • template <typename C, typename R> void ofxSubscribeOsc(int port, const string * &address, const C &that, R (C::*callback)(ofxOscMessage &) const);
  • template <typename C, typename R> void ofxSubscribeOsc(int port, const string &address, const C *that, R (C::*callback)(ofxOscMessage &) const);
    • TODO

lambda callback

  • void ofxSubscribeOsc(int port, const string &address, std::function<void(ofxOscMessage &)> &callback);
    • (if you use 0.9.0~)

bind value/function/method to OSC message has address incoming from port.

if use function/method, then call callback(mess) or (that.\*callback)(mess) or (that->\*callback)(mess), std::function<void(ofxOscMessage &)> when receive OSC message mess.

Unscribe

  • void ofxUnsubscribeOSC(int port, const string &address);

unbind OSC message has address incoming from port.

  • void ofxUnsubscribeOSC(int port);

unbind all OSC messages incoming from port.

See class ofxOscSubscriberManager, class ofxOscSubscriber

ofxSetLeakedOscPicker

  • void ofxSetLeakedOscPicker(int port, void (*callback)(ofxOscMessage &))

  • template <typename C, typename R> void ofxSetLeakedOscPicker(int port, C *that, R (C::*callback)(ofxOscMessage &))

  • template <typename C, typename R> void ofxSetLeakedOscPicker(int port, C &that, R (C::*callback)(ofxOscMessage &))

  • template <typename C, typename R> void ofxSetLeakedOscPicker(int port, const C *that, R (C::*callback)(ofxOscMessage &) const)

  • template <typename C, typename R> void ofxSetLeakedOscPicker(int port, const C &that, R (C::*callback)(ofxOscMessage &) const)

  • void ofxSetLeakedOscPicker(int port, std::function<void(ofxOscMessage &)> &callback)

    • if you use 0.9.0~

set callback for port. this callback is kick when receive OSC message has not binded address.

  • void ofxRemoveLeakedOscPicker(int port)

remove callback.

See Legacy style pick up leaked OSC

ofxPublishOsc

  • template <typename T> void ofxPublishOsc(const string &ip, int port, const string &address, T &value, bool whenValueIsChanged = true);
  • template <typename T> void ofxPublishOsc(const string &ip, int port, const string &address, T (*getter)(), bool whenValueIsChanged = true);
  • template <typename T, typename U> void ofxPublishOsc(const string &ip, int port, const string &address, U *that, T (U::*getter)(), bool whenValueIsChanged = true);

publish value / getter() / (that.*getter)() to OSC message has address to ip:port. if whenValueIsChanged is set to false, then we send binded value every frame after App::update.

ofxPublishOscIf

  • template <...> void ofxPublishOscIf(bool &condition, const string &ip, int port, const string &address, ...);
  • template <...> void ofxPublishOscIf(bool (*condition)(), const string &ip, int port, const string &address, ...);
  • template <..., typename C> void ofxPublishOscIf(C *condition, bool (C::*method)(), const string &ip, int port, const string &address, ...);
  • template <..., typename C> void ofxPublishOscIf(C &condition, bool (C::*method)(), const string &ip, int port, const string &address, ...);

if condition / condition() / (condition.*method)() is true then publish arguments are same pattern as ofxPublishOsc. (only whenValueChanged is eliminated. whenValueChanged is always true.)

  • void ofxUnpublishOSC(const string &ip, int port, const string &address);

unpublish OSC message has address is send to ip:port.

  • void ofxUnpublishOSC(const string &ip, int port);

unpublish all OSC messages is send to ip:port.

ofxPublishAsArray

  • template <typename T, size_t size> typename array_type<T, size>::type ofxPublishAsArray(T *ptr);
    • where array_type<T, size>::type is T (&)[size]

cast value is typed T * -> value is typed T (&)[size]

  • template <typename T, size_t size> typename array_type<T, size>::fun ofxPublishAsArray(T *(*getter)());
    • where array_type<T, size>::fun is array_type<T, size>::type (*)()

cast function returns T * -> function returns T (&)[size]

  • template <typename T, size_t size> typename array_method<T, size, U>::method ofxPublishAsArray(T *(U::*getter)());
    • where array_method<T, size, U>::method is array_type<T, size>::type (U:*)()

cast method of U returns T * -> method of U returns T (&)[size]

Example
struct P {
	int *getFooPtr() { return foo; }
private:
	int foo[8];
};

P p;
float *bar = new float[12];

...

ofxPublishOsc("localhost", 9005, "/foo", p, ofxPublishAsArray<int, 8>(&P::getFooPtr));
ofxPublishOsc("localhost", 9005, "/bar", ofxPublishAsArray<float, 12>(bar));

ofxSetPublisherUsingBundle

  • ofxSetPublisherUsingBundle(bool bUseBundle)

set to send messages with bundle

See class ofxOscPublisherManager, class ofxOscPublisher

Advanced API

class ofxOscSubscriberManager

  • static ofxOscSubscriberManager &getSharedInstance();

return sharedInstance.

  • static ofxOscSubscriber &getOscSubscriber(int port);

return OSC subscriber is binded to port.

class ofxOscSubscriber

  • template <typename T> void subscribe(const string &address, T &value);
  • void subscribe(const string &address, void (*callback)(ofxOscMessage &));
  • template <typename T> void subscribe(const string &address, T &that, void (T::*callback)(ofxOscMessage &));
  • template <typename T> void subscribe(const string &address, T * that, void (T::*callback)(ofxOscMessage &));

bind value/function/method to OSC message has address.

  • void unsubscribe(const string &address);

unbind OSC message has address.

  • void unsubscribe();

unbind all OSC messages.

How to subscribe ofParameterGroup

to subscribing value into ofParameterGroup, is different to others.

we need key for search parameter from parameter group.

so, we have to add key to first argument of OSC message.

for example, we setup parameter group and parameter like this:

ofParameterGroup group;
ofParameter<float> float_x;
ofParameter<float> float_y;
ofParameter<ofColor> color;

...

float_x.setName("x");
float_y.setName("y");
color.setName("c");

group.add(float_y); // float_y has index 0 and name "y"
group.add(float_x); // float_x has index 1 and name "x"
group.add(color); // color has index 2 and name "c"

ofxSubscribeOsc(9005, "/param_group", group);

then, we construct message like this:

ofxOscMessage mx, my;

mx.setAddress("/param_group");
mx.addArgAsString("x");
mx.addArgAsFloat(1.0f);
sender.sendMessage(mx); // this value set to float_x

my.setAddress("/param_group");
my.addArgAsString("y");
my.addArgAsFloat(2.0f);
sender.sendMessage(my); // this value set to float_y

ofxOscMessage m_0, m_1;

m0.setAddress("/param_group");
m0.addArgAsInt(0);
m0.addArgAsFloat(1.0f);
sender.sendMessage(m0); // !! this value set to float_y

m1.setAddress("/param_group");
m1.addArgAsInt(1);
m1.addArgAsFloat(2.0f);
sender.sendMessage(m1); // !! this value set to float_x 

ofxOscMessage mc;
mc.setAddress("/param_group");
mc.addArgAsString("c");
mc.addArgAsInt(255);
mc.addArgAsInt(0);
mc.addArgAsInt(0);
mc.addArgAsInt(255);
sender.sendMessage(mc); // color will set to red

setLeakPicker

  • void setLeakPicker(void (*callback)(ofxOscMessage &));
  • template <typename T> void setLeakPicker(T *that, void (T::*callback)(ofxOscMessage &));
  • template <typename T> void setLeakPicker(T &that, void (T::*callback)(ofxOscMessage &));

set callback for port. this callback is kick when receive OSC message has not binded address.

  • void removeLeakPicker();

remove callback picks leaked message.

How to "Legacy style pick up leaked OSC"

if you don't use setLeakPicker to a port, then you can pick leaked messages manually like this:

while(ofxGetOscSubScriber(port).hasWaitingLeakedOscMessages()) {
	ofxOscMessage m;
	ofxGetOscSubscriber(9005).getNextLeakedOscMessage(m);
	ofLogNotice() << m.getAddress();
}

please note that argument of getNextLeakedOscMessage is not as address (i.e. ofxOscMessage *). you can pass ofxOscMessage and we will receive as ofxOscMessage & and set something.

class ofxOscPublisherManager

  • static ofxOscPublisherManager &getSharedInstance();

return sharedInstance.

  • static ofxOscPublisher &getOscPublisher(const string &ip, int port);

return OSC publisher send to ip:port.

class ofxOscPublisher

  • template <typename T> void publish(const string &address, T &value, bool whenValueIsChanged = true);
  • template <typename T> void publish(const string &address, T (*getter)(), bool whenValueIsChanged = true);
  • template <typename T, typename U> void publish(const string &address, U *that, T (U::*getter)(), bool whenValueIsChanged = true);

publish value / getter() / (that.*getter)() to OSC message has address to ip:port. if whenValueIsChanged is set to false, then we send binded value every frame after App::update.

  • void unpublish(const string &address);

unpublish OSC message has address.

  • void ofxUnpublishOSC();

unpublish all OSC messages.