--[[============================================================================
Renoise OSC API Reference
============================================================================]]--

--[[

This reference describes the built-in OSC (Open Sound Control) support for
Lua scripts in Renoise. OSC can be used in combination with sockets to
send/receive OSC tagged data over process boundaries, or to exchange data
across computers in a network (Internet).

Have a look at <http://opensoundcontrol.org> for general info about OSC.

Please read the INTRODUCTION first to get an overview about the complete
API, and scripting for Renoise in general...

Do not try to execute this file. It uses a .lua extension for markup only.


-------- Examples

-- For some small examples on how to use the OSC and Sockets API, have a
-- look at the code snippets in "Snippets/Osc.lua".

]]--


--==============================================================================
-- Osc
--==============================================================================

--------------------------------------------------------------------------------
-- renoise.Osc
--------------------------------------------------------------------------------

-- De-packetizing raw (socket) data to OSC messages or bundles
-- converts the binary data to an OSC message or bundle. If the data does not
-- look like an OSC message, or the message contains errors, nil is returned
-- as first argument and the second return value will contain the error.
-- If de-packetizing was successful, either a renoise.Osc.Bundle or Message
-- object is returned. Bundles may contain multiple messages or nested bundles.
renoise.Osc.from_binary_data(binary_data)
  -> [Osc.Bundle or Osc.Message object or nil, error or nil]


--------------------------------------------------------------------------------
-- renoise.Osc.Message
--------------------------------------------------------------------------------

-------- Create

-- Create a new OSC message with the given pattern and optional arguments.
-- When arguments are specified, they must be specified as a table of:
--
-- > { tag="X", value=SomeValue }
--
-- "tag" is a standard OSC type tag. "value" is the arguments value expressed 
-- by a Lua type. The value must be convertible to the specified tag, which 
-- means, you cannot for example specify an "i" (integer) as type and then pass 
-- a string as the value. Use a number value instead. Not all tags require a 
-- value, like the T,F boolean  tags. Then a "value" field should not be 
-- specified. For more info, see: <http://opensoundcontrol.org/spec-1_0>
--
-- Valid tags are (OSC Type Tag, Type of corresponding value)
-- 
-- + i,    int32
-- + f,    float32
-- + s,    OSC-string
-- + b,    OSC-blob
-- + h,    64 bit big-endian two's complement integer
-- + t,    OSC-timetag
-- + d,    64 bit ("double") IEEE 754 floating point number
-- + S,    Alternate type represented as an OSC-string
-- + c,    An ascii character, sent as 32 bits
-- + r,    32 bit RGBA color
-- + m,    4 byte MIDI message. Bytes from MSB to LSB are: port id, 
--         status byte, data1, data2
-- + T,    True. No value needs to be specified.
-- + F,    False. No value needs to be specified.
-- + N,    Nil. No value needs to be specified.
-- + I,    Infinitum. No value needs to be specified.
-- + [ ],  Indicates the beginning, end of an array. (Currently not 
--         supported by Renoise.)
--
renoise.Osc.Message(pattern [, table of {tag, value} arguments])


-------- Properties

-- The message pattern (e.g. "/renoise/transport/start")
message.pattern
  -> [read-only, string]

-- Table of `{tag="X", value=SomeValue}` that represents the message arguments.
-- see renoise.Osc.Message "create" for more info.
message.arguments
  -> [read-only, table of {tag, value} tables]

-- Raw binary representation of the messsage, as needed when e.g. sending the
-- message over the network through sockets.
message.binary_data
  -> [read-only, raw string]


--------------------------------------------------------------------------------
-- renoise.Osc.Bundle
--------------------------------------------------------------------------------

-------- Create

-- Create a new bundle by specifying a time-tag and one or more messages.
-- If you do not know what to do with the time-tag, use os.clock(),
-- which simply means "now". Messages must be renoise.Osc.Message objects.
-- Nested bundles (bundles in bundles) are right now not supported.
renoise.Osc.Bundle(pattern, single_message_or_table_of_messages)


-------- Properties

-- Time value of the bundle.
bundle.timetag
  -> [read-only, number]

-- Access to the bundle elements (table of messages or bundle objects)
bundle.elements
  -> [read-only, table of renoise.Osc.Message or renoise.Osc.Bundle objects]

-- Raw binary representation of the bundle, as needed when e.g. sending the
-- message over the network through sockets.
bundle.binary_data
  -> [read-only, raw string]

