doc: add more docs
This commit is contained in:
Wim Taymans
parent
736e9cc94c
commit
aad69d22c1
|
|
@ -0,0 +1,356 @@
|
|||
/** \page page_native_protocol Native Protocol
|
||||
|
||||
PipeWire has a pluggable client/server IPC protocol.
|
||||
|
||||
The reference implementation uses unix sockets and is implemented in
|
||||
\ref page_module_protocol_native.
|
||||
|
||||
We document the messages here.
|
||||
|
||||
# Message header
|
||||
|
||||
Each message on the unix socket contains a 16 bytes header and a
|
||||
variable length payload size:
|
||||
|
||||
```
|
||||
0 1 2 3
|
||||
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| Id |
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| opcode | size |
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| seq |
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| n_fds |
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| payload POD |
|
||||
. .
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| optional footer POD |
|
||||
. .
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
```
|
||||
|
||||
|
||||
These are four uint32 words to be read in native endianness.
|
||||
|
||||
Id: the message id this is the destination resource/proxy id
|
||||
opcode: the opcode on the resource/proxy interface
|
||||
size: the size of the payload and optional footer of the message
|
||||
seq: an increasing sequence number for each message
|
||||
n_fds: number of file descriptors in this message.
|
||||
|
||||
The sender should send along with each message the fds that belong to
|
||||
the message. If there are more than the maximum number of fds in the
|
||||
message than can fit in one message, the message is split into multiple
|
||||
parts.
|
||||
|
||||
The payload is a single POD see \ref page_spa_pod for details.
|
||||
|
||||
After the payload, there is an optional footer POD object.
|
||||
|
||||
# Making a connection
|
||||
|
||||
|
||||
|
||||
|
||||
# Core proxy/resource
|
||||
|
||||
The core is always the object with Id 0.
|
||||
|
||||
## Core Methods (Id 0)
|
||||
|
||||
### Hello (Opcode 1)
|
||||
|
||||
The first message sent by a client is the Hello message and contains the
|
||||
version number of the client.
|
||||
|
||||
```
|
||||
Struct(
|
||||
Int: version
|
||||
)
|
||||
```
|
||||
|
||||
The version is 3.
|
||||
|
||||
### Sync (Opcode 2)
|
||||
|
||||
The Sync message will result in a Done event from the server. When the Done
|
||||
event is received, the client can be sure that all operations before the Sync
|
||||
method have been completed.
|
||||
|
||||
```
|
||||
Struct(
|
||||
Int: id
|
||||
Int: seq
|
||||
)
|
||||
```
|
||||
|
||||
id: the id will be returned in the Done event.
|
||||
seq: is usually generated automatically and will be returned in the Done event.
|
||||
|
||||
### Pong (Opcode 3)
|
||||
|
||||
Is sent from the client to the server when the server emits the Ping event.
|
||||
The id and seq should be copied from the Ping event.
|
||||
|
||||
```
|
||||
Struct(
|
||||
Int: id
|
||||
Int: seq
|
||||
)
|
||||
```
|
||||
|
||||
### Error (Opcode 4)
|
||||
|
||||
An error occured in an object on the client.
|
||||
|
||||
```
|
||||
Struct(
|
||||
Int: id
|
||||
Int: seq
|
||||
Int: res
|
||||
String: message
|
||||
)
|
||||
```
|
||||
|
||||
id: The id of the proxy that is in error.
|
||||
seq: a seq number from the failing request (if any)
|
||||
res: a negative errno style error code
|
||||
message: an error message
|
||||
|
||||
### GetRegistry (Opcode 5)
|
||||
|
||||
A client requests to bind to the registry object and list the available objects
|
||||
on the server.
|
||||
|
||||
Like with all bindings, first the client allocates a new proxy id and puts this
|
||||
as the new_id field. Methods and Events can then be sent and received on the
|
||||
new_id (in the message Id field).
|
||||
|
||||
```
|
||||
Struct(
|
||||
Int: version
|
||||
Int: new_id
|
||||
)
|
||||
```
|
||||
|
||||
version: the version of the registry interface used on the client
|
||||
new_id: the id of the new proxy with the registry interface
|
||||
|
||||
### CreateObject (Opcode 6)
|
||||
|
||||
Create a new object from a factory of a certain type.
|
||||
|
||||
The client allocates a new_id for the proxy. The server will allocate a new
|
||||
resource with the same new_id and from then on, Methods and Events will be
|
||||
exchanged between the new object of the given type.
|
||||
|
||||
```
|
||||
Struct(
|
||||
String: factory_name
|
||||
String: type
|
||||
Int: version
|
||||
Struct(
|
||||
Int: n_items
|
||||
(String: key
|
||||
String: value)*
|
||||
): props
|
||||
Int: new_id
|
||||
)
|
||||
```
|
||||
|
||||
factory_name: the name of a server factory object to use
|
||||
type: the type of the object to create, this is also the type of the
|
||||
interface of the new_id proxy.
|
||||
props: extra properties to create the object
|
||||
new_id: the proxy id of the new object
|
||||
|
||||
### Destroy (Opcode 7)
|
||||
|
||||
Destroy an object.
|
||||
|
||||
```
|
||||
Struct(
|
||||
Int: id
|
||||
)
|
||||
```
|
||||
|
||||
id: the proxy id of the object to destroy.
|
||||
|
||||
## Core Events
|
||||
|
||||
Core events are emited by the server.
|
||||
|
||||
### Info (0)
|
||||
|
||||
Emited by the server upon connection with the more information about the
|
||||
server.
|
||||
|
||||
```
|
||||
Struct(
|
||||
Int: id
|
||||
Int: cookie
|
||||
String: user_name
|
||||
String: host_name
|
||||
String: version
|
||||
String: name
|
||||
Long: change_mask
|
||||
Struct(
|
||||
Int: n_items
|
||||
(String: key
|
||||
String: value)*
|
||||
): props
|
||||
)
|
||||
```
|
||||
|
||||
id: the id of the server (0)
|
||||
cookie: a unique cookie for this server
|
||||
user_name: the name of the user running the server
|
||||
host_name: the name of the host running the server
|
||||
version: a version string of the server
|
||||
name: the name of the server
|
||||
change_mask: a set of bits with changes to the info
|
||||
- 1<<0: Properties changed
|
||||
props: optional key/value properties
|
||||
|
||||
### Done (1)
|
||||
|
||||
Emited as a result of a client Sync method.
|
||||
|
||||
```
|
||||
Struct(
|
||||
Int: id
|
||||
Int: seq
|
||||
)
|
||||
```
|
||||
|
||||
id and seq are passed from the client Sync request.
|
||||
|
||||
### Ping (2)
|
||||
|
||||
Emited by the server when it wants to check if a client is alive or ensure
|
||||
that it has processed the previous events.
|
||||
|
||||
```
|
||||
Struct(
|
||||
Int: id
|
||||
Int: seq
|
||||
)
|
||||
```
|
||||
|
||||
id: the object id to ping
|
||||
seq: usually automatically generated. The client should pass this in the Pong
|
||||
method reply.
|
||||
|
||||
### Error (3)
|
||||
|
||||
The error event is sent out when a fatal (non-recoverable)
|
||||
error has occurred. The id argument is the proxy object where
|
||||
the error occurred, most often in response to a request to that
|
||||
object. The message is a brief description of the error,
|
||||
for (debugging) convenience.
|
||||
|
||||
```
|
||||
Struct(
|
||||
Int: id
|
||||
Int: seq
|
||||
Int: res
|
||||
String: message
|
||||
)
|
||||
```
|
||||
|
||||
id: The id of the resource that is in error.
|
||||
seq: a seq number from the failing request (if any)
|
||||
res: a negative errno style error code
|
||||
message: an error message
|
||||
|
||||
|
||||
### RemoveId (4)
|
||||
|
||||
This event is used internally by the object ID management
|
||||
logic. When a client deletes an object, the server will send
|
||||
this event to acknowledge that it has seen the delete request.
|
||||
When the client receives this event, it will know that it can
|
||||
safely reuse the object ID.
|
||||
|
||||
```
|
||||
Struct(
|
||||
Int: id
|
||||
)
|
||||
```
|
||||
|
||||
### BoundId (5)
|
||||
|
||||
This event is emitted when a local object ID is bound to a
|
||||
global ID. It is emitted before the global becomes visible in the
|
||||
registry. This event is deprecated, the BoundProps event should
|
||||
be used because it also contains extra properties.
|
||||
|
||||
```
|
||||
Struct(
|
||||
Int: id
|
||||
Int: global_id
|
||||
)
|
||||
```
|
||||
|
||||
id: a proxy id
|
||||
global_id: the global_id as it will appear in the registry.
|
||||
|
||||
### AddMem (6)
|
||||
|
||||
Memory is given to a client as fd of a certain memory type.
|
||||
Further references to this fd will be made with the per memory
|
||||
unique identifier id.
|
||||
|
||||
```
|
||||
Struct(
|
||||
Int: id
|
||||
Id: type
|
||||
Fd: fd
|
||||
Int: flags
|
||||
)
|
||||
```
|
||||
|
||||
id: a server allocated id for this memory
|
||||
type: the memory type, see enum spa_data_type
|
||||
fd: the index of the fd sent with this message
|
||||
flags: extra flags
|
||||
|
||||
### RemoveMem (7)
|
||||
|
||||
Remove memory for a client with the given id
|
||||
|
||||
```
|
||||
Struct(
|
||||
Int: id
|
||||
)
|
||||
```
|
||||
|
||||
id: the id of the memory to remove. This is the Id from
|
||||
AddMem.
|
||||
|
||||
### BoundProps (8)
|
||||
|
||||
This event is emitted when a local object ID is bound to a
|
||||
global ID. It is emitted before the global becomes visible in the
|
||||
registry.
|
||||
|
||||
```
|
||||
Struct(
|
||||
Int: id
|
||||
Int: global_id
|
||||
Struct(
|
||||
Int: n_items
|
||||
(String: key
|
||||
String: value)*
|
||||
): props
|
||||
)
|
||||
```
|
||||
|
||||
id: a proxy id
|
||||
global_id: the global_id as it will appear in the registry.
|
||||
props: the properties of the global
|
||||
|
||||
*/
|
||||
|
|
@ -11,6 +11,7 @@
|
|||
- \subpage page_library
|
||||
- \subpage page_dma_buf
|
||||
- \subpage page_scheduling
|
||||
- \subpage page_native_protocol
|
||||
|
||||
|
||||
# Components
|
||||
|
|
|
|||
464
doc/spa-pod.dox
464
doc/spa-pod.dox
|
|
@ -517,10 +517,468 @@ result = spa_pod_builder_add_object(&b,
|
|||
|
||||
# POD Layout
|
||||
|
||||
Each POD has a 32 bits size field, followed by a 32 bits type field. The size
|
||||
field specifies the size following the type field.
|
||||
A POD always starts with a size/type pair of uint32_t in native endianness,
|
||||
followed by size in bytes of the payload data and padding. See
|
||||
\ref page_spa_pod for more details.
|
||||
|
||||
Each POD is aligned to an 8 byte boundary.
|
||||
The payload is always padded to 8 bytes so that a complete pod is always
|
||||
a multiple of 8 bytes.
|
||||
|
||||
0 1 2 3
|
||||
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| size |
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| type |
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| payload ... |
|
||||
. | ... padding .
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
|
||||
The total size of the POD is thus ROUND_UP_8(8 + size).
|
||||
|
||||
# POD Types
|
||||
|
||||
Here follows the layout of the POD types.
|
||||
|
||||
## None (1)
|
||||
|
||||
Type 1 is the None type or the null pointer. It has a size of 0 and thus
|
||||
no payload.
|
||||
|
||||
0 1 2 3
|
||||
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| 0 |
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| 1 |
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
|
||||
## Bool (2)
|
||||
|
||||
Type 2 is the Bool type. I contains a true or false value. The value is
|
||||
stored in a int32, a value of 0 is false, any other value is true.
|
||||
|
||||
0 1 2 3
|
||||
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| 4 |
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| 2 |
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| value (int32) |
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| padding |
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
|
||||
## Id (3)
|
||||
|
||||
An id is stored as a uint32. The id refers to an index in a table where more
|
||||
information about the value can be found. This is typically a type table
|
||||
containing some well known ids.
|
||||
|
||||
0 1 2 3
|
||||
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| 4 |
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| 3 |
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| id (uint32) |
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| padding |
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
|
||||
## Int (4)
|
||||
|
||||
A 32 bit signed integer.
|
||||
|
||||
0 1 2 3
|
||||
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| 4 |
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| 4 |
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| value (int32) |
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| padding |
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
|
||||
## Long (5)
|
||||
|
||||
A 64 bit signed integer.
|
||||
|
||||
0 1 2 3
|
||||
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| 4 |
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| 5 |
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| value (int64) |
|
||||
+ +
|
||||
| |
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
|
||||
## Float (6)
|
||||
|
||||
A 32 bit float value.
|
||||
|
||||
0 1 2 3
|
||||
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| 4 |
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| 6 |
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| value (float32) |
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| padding |
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
|
||||
## Double (7)
|
||||
|
||||
A 64 bit float value.
|
||||
|
||||
0 1 2 3
|
||||
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| 4 |
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| 7 |
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| value (float64) |
|
||||
+ +
|
||||
| |
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
|
||||
## String (8)
|
||||
|
||||
A string. This does not have to be valid UTF8 but it is 0 terminated.
|
||||
The size field is set to the length of the string, including the 0
|
||||
byte.
|
||||
|
||||
0 1 2 3
|
||||
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| size |
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| 8 |
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| chars .... |
|
||||
. .
|
||||
| ... 0 | padding.. |
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
|
||||
|
||||
## Bytes (9)
|
||||
|
||||
A byte array. The size field is set to the number of bytes.
|
||||
|
||||
0 1 2 3
|
||||
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| size |
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| 9 |
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| bytes .... |
|
||||
. .
|
||||
| | padding.. |
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
|
||||
## Rectangle (10)
|
||||
|
||||
A Rectangle.
|
||||
|
||||
0 1 2 3
|
||||
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| 8 |
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| 10 |
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| width (uint32) |
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| height (uint32) |
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
|
||||
## Fraction (11)
|
||||
|
||||
A Fraction.
|
||||
|
||||
0 1 2 3
|
||||
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| 8 |
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| 11 |
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| num (uint32) |
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| denom (uint32) |
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
|
||||
## Bitmap (12)
|
||||
|
||||
A bitmap. Stored as bits in uint8. size is the number of bytes with
|
||||
bits.
|
||||
|
||||
0 1 2 3
|
||||
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| size |
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| 12 |
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| bits (uint8) ... |
|
||||
. .
|
||||
| | padding.. |
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
|
||||
## Array (13)
|
||||
|
||||
An array is an array of (basic) types. In principle the array can contain
|
||||
any type as long as each item in the array has the same child_size and
|
||||
child_type.
|
||||
|
||||
0 1 2 3
|
||||
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| size |
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| 13 |
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| child_size |
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| child_type |
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| child1 (child_size bytes) ... |
|
||||
. .
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
. .
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| childN (child_size bytes) ... |
|
||||
. .
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
|
||||
We describe Array types with a shortcut like:
|
||||
|
||||
Array[Int](<val1>,<val2>,...)
|
||||
|
||||
## Struct (14)
|
||||
|
||||
Multiple PODs can be combined into a struct:
|
||||
|
||||
0 1 2 3
|
||||
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| size |
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| 14 (Struct) |
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| size1 |
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| type1 |
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| payload 1... |
|
||||
. | ... padding .
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
. .
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| sizeN |
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| typeN |
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| payloadN ... |
|
||||
. | ... padding .
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
|
||||
We describe Struct types with a shortcut like:
|
||||
|
||||
Struct(
|
||||
<pod1 type> : <pod1 description>,
|
||||
<pod2 type> : <pod2 description>,
|
||||
...)
|
||||
|
||||
The type of a struct is 14 and the size the total sum in bytes of all
|
||||
PODs (with padding) inside the struct.
|
||||
|
||||
## Object (15)
|
||||
|
||||
An object contains a set of of properties.
|
||||
|
||||
0 1 2 3
|
||||
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| size |
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| 15 |
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| object_type |
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| object_id |
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| property1 |
|
||||
. .
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
. .
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| propertyN |
|
||||
. .
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
|
||||
object_type is one of the well defined object types.
|
||||
object_id is extra information about the context of the object.
|
||||
|
||||
Each property is as follows:
|
||||
|
||||
0 1 2 3
|
||||
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| key (uint32) |
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| flags (uint32) |
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| POD value ... |
|
||||
. .
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
|
||||
Object are written with a shortcut as:
|
||||
|
||||
Object[type,id](
|
||||
key1: <pod1>,
|
||||
key2: <pod1>,
|
||||
...)
|
||||
|
||||
## Sequence (16)
|
||||
|
||||
A sequence is a series of times events. It is usually used for transporting
|
||||
MIDI and control updates.
|
||||
|
||||
0 1 2 3
|
||||
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| size |
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| 16 |
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| unit |
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| pad |
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| control1 |
|
||||
. .
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
. .
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| controlN |
|
||||
. .
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
|
||||
The unit field and pad is currently set to 0.
|
||||
|
||||
Each control look like:
|
||||
|
||||
0 1 2 3
|
||||
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| offset (uint32) |
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| type (uint32) |
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| POD value ... |
|
||||
. .
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
|
||||
offset: the offset relative to the current graph clock time.
|
||||
type: the type of control:
|
||||
- SPA_CONTROL_Properties (1) value contains a SPA_TYPE_OBJECT_Props
|
||||
- SPA_CONTROL_Midi (2) value is a Bytes with raw midi data
|
||||
- SPA_CONTROL_OSC (3) value contains Bytes with an OSC packet
|
||||
|
||||
|
||||
## Pointer (17)
|
||||
|
||||
A generic pointer to some memory region. Pointer types are usually not serialized.
|
||||
|
||||
0 1 2 3
|
||||
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| size |
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| 17 |
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| type |
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| padding (must be 0) |
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| native pointer value ... |
|
||||
. | .. padding .
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
|
||||
|
||||
## Fd (18)
|
||||
|
||||
A file descriptor stored as int64. When serializing, the file descriptor
|
||||
is modified to contain the index of the fd in the message.
|
||||
|
||||
0 1 2 3
|
||||
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| size |
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| 18 |
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| fd (int64) ... |
|
||||
+ +
|
||||
| |
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
|
||||
## Choice (19)
|
||||
|
||||
A choice contains an array of possible values.
|
||||
|
||||
0 1 2 3
|
||||
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| size |
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| 19 |
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| type |
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| flags |
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| child_size |
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| child_type |
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| child1 (child_size bytes) ... |
|
||||
. .
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
. .
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| childN (child_size bytes) ... |
|
||||
. .
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
|
||||
type: one of possible values:
|
||||
- None (0) : only child1 is an valid option
|
||||
- Range (1) : child1 is a default value, options are between
|
||||
child2 and child3 in the value array.
|
||||
- Step (2) : child1 is a default value, options are between
|
||||
child2 and child3, in steps of child4 in the value array.
|
||||
- Enum (3) : child1 is a default value, options are any value from
|
||||
the value array, prefered values come first.
|
||||
- Flags (4) : child1 is a default value, options are any value from
|
||||
the value array, prefered values come first.
|
||||
flags: must be 0
|
||||
|
||||
## Pod (20)
|
||||
|
||||
The value id the POD itself.
|
||||
|
||||
|
||||
\addtogroup spa_pod
|
||||
|
|
|
|||
Loading…
Reference in New Issue