package vendor:portmidi



    DeviceID ¶

    DeviceID :: distinct i32
    Related Procedures With Parameters
    Related Procedures With Returns
    Related Constants

    DeviceInfo ¶

    DeviceInfo :: struct {
    	structVersion: i32,
    	// *< this internal structure version 
    	interf:        cstring,
    	// *< underlying MIDI API, e.g. MMSystem or DirectX 
    	name:          cstring,
    	// *< device name, e.g. USB MidiSport 1x1 
    	input:         b32,
    	// *< true iff input is available 
    	output:        b32,
    	// *< true iff output is available 
    	opened:        b32,
    Related Procedures With Returns

    Error ¶

    Error :: enum i32 {
    	NoError            = 0, 
    	NoData             = 0,      // *< A "no error" return that also indicates no data avail.
    	GotData            = 1,      // *< A "no error" return that also indicates data available
    	HostError          = -10000, 
    	InvalidDeviceId,             // out of range or 
    	                   * output device when input is requested or 
    	                   * input device when output is requested or
    	                   * device is already opened
    	BadPtr,                      // Stream parameter is nil or
    	         * stream is not opened or
    	         * stream is output when input is required or
    	         * stream is input when output is required
    	BadData,                     // illegal midi data, e.g. missing EOX
    	BufferMaxSize,               // buffer is already as large as it can be
    Related Procedures With Parameters
    Related Procedures With Returns

    Event ¶

    Event :: struct {
    	message:   Message,
    	timestamp: Timestamp,


    All midi data comes in the form of Event structures. A sysex
    message is encoded as a sequence of Event structures, with each
    structure carrying 4 bytes of the message, i.e. only the first
    Event carries the status byte.
    Note that MIDI allows nested messages: the so-called "real-time" MIDI 
    messages can be inserted into the MIDI byte stream at any location, 
    including within a sysex message. MIDI real-time messages are one-byte
    messages used mainly for timing (see the MIDI spec). PortMidi retains 
    the order of non-real-time MIDI messages on both input and output, but 
    it does not specify exactly how real-time messages are processed. This
    is particulary problematic for MIDI input, because the input parser 
    must either prepare to buffer an unlimited number of sysex message 
    bytes or to buffer an unlimited number of real-time messages that 
    arrive embedded in a long sysex message. To simplify things, the input
    parser is allowed to pass real-time MIDI messages embedded within a 
    sysex message, and it is up to the client to detect, process, and 
    remove these messages as they arrive.
    When receiving sysex messages, the sysex message is terminated
    by either an EOX status byte (anywhere in the 4 byte messages) or
    by a non-real-time status byte in the low order byte of the message.
    If you get a non-real-time status byte but there was no EOX byte, it 
    means the sysex message was somehow truncated. This is not
    considered an error; e.g., a missing EOX can result from the user
    disconnecting a MIDI cable during sysex transmission.
    A real-time message can occur within a sysex message. A real-time 
    message will always occupy a full Event with the status byte in 
    the low-order byte of the Event message field. (This implies that
    the byte-order of sysex bytes and real-time message bytes may not
    be preserved -- for example, if a real-time message arrives after
    3 bytes of a sysex message, the real-time message will be delivered
    first. The first word of the sysex message will be delivered only
    after the 4th byte arrives, filling the 4-byte Event message field.
    The timestamp field is observed when the output port is opened with
    a non-zero latency. A timestamp of zero means "use the current time",
    which in turn means to deliver the message with a delay of
    latency (the latency parameter used when opening the output port.)
    Do not expect PortMidi to sort data according to timestamps -- 
    messages should be sent in the correct order, and timestamps MUST 
    be non-decreasing. See also "Example" for OpenOutput() above.
    A sysex message will generally fill many Event structures. On 
    output to a Stream with non-zero latency, the first timestamp
    on sysex message data will determine the time to begin sending the 
    message. PortMidi implementations may ignore timestamps for the 
    remainder of the sysex message. 
    On input, the timestamp ideally denotes the arrival time of the 
    status byte of the message. The first timestamp on sysex message 
    data will be valid. Subsequent timestamps may denote 
    when message bytes were actually received, or they may be simply 
    copies of the first timestamp.
    Timestamps for nested messages: If a real-time message arrives in 
    the middle of some other message, it is enqueued immediately with 
    the timestamp corresponding to its arrival time. The interrupted 
    non-real-time message or 4-byte packet of sysex data will be enqueued 
    later. The timestamp of interrupted data will be equal to that of
    the interrupting real-time message to insure that timestamps are

    Message ¶

    Message :: distinct i32
    Related Procedures With Parameters
    Related Procedures With Returns

    Queue ¶

    Queue :: distinct rawptr
    Related Procedures With Parameters
    Related Procedures With Returns

    Stream ¶

    Stream :: distinct rawptr

    A single Stream is a descriptor for an open MIDI device.

    Related Procedures With Parameters

    TimeProc ¶

    TimeProc :: proc "c" (time_info: rawptr) -> Timestamp
    Related Procedures With Parameters

    Timestamp ¶

    Timestamp :: distinct i32

    * Timestamp is used to represent a millisecond clock with arbitrary start time. The type is used for all MIDI timestampes and clocks.

    Related Procedures With Parameters





    FILT_ACTIVE :: 1 << 0x0E

    Filter bit-mask definitions filter active sensing messages (0xFE):



    filter both channel and poly aftertouch



    filter channel aftertouch (most midi controllers use this) (0xD0-0xDF)


    FILT_CLOCK :: 1 << 0x08

    filter MIDI clock message (0xF8)


    FILT_CONTROL :: 1 << 0x1B

    Control Changes (CC's) (0xB0-0xBF)

    FILT_FD ¶

    FILT_FD :: 1 << 0x0D

    filter undefined FD messages

    FILT_MTC ¶

    FILT_MTC :: 1 << 0x01

    MIDI Time Code (0xF1)


    FILT_NOTE :: (1 << 0x19) | (1 << 0x18)

    filter note-on and note-off (0x90-0x9F and 0x80-0x8F


    FILT_PITCHBEND :: 1 << 0x1E

    Pitch Bender (0xE0-0xEF


    FILT_PLAY :: (1 << 0x0A) | (1 << 0x0C) | (1 << 0x0B)

    filter play messages (start 0xFA, stop 0xFC, continue 0xFB)



    per-note aftertouch (0xA0-0xAF)


    FILT_PROGRAM :: 1 << 0x1C

    Program changes (0xC0-0xCF)



    filter all real-time messages


    FILT_RESET :: 1 << 0x0F

    filter reset messages (0xFF)


    FILT_SONG_POSITION :: 1 << 0x02

    Song Position (0xF2)


    FILT_SONG_SELECT :: 1 << 0x03

    Song Select (0xF3)


    FILT_SYSEX :: 1 << 0x00

    filter system exclusive messages (0xF0):



    All System Common messages (mtc, song position, song select, tune request)


    FILT_TICK :: 1 << 0x09

    filter tick messages (0xF9)


    FILT_TUNE :: 1 << 0x06

    Tuning request (0xF6)



    filter undefined real-time messages


    HDRLENGTH :: 50



    any host error msg will occupy less than this number of characters

    NoDevice ¶

    NoDevice :: DeviceID(-1)




    This section is empty.


    Abort ¶

    Abort :: proc "c" (stream: Stream) -> Error ---


    	Abort() terminates outgoing messages immediately
    	The caller should immediately close the output port;
    	this call may result in transmission of a partial midi message.
    	There is no abort for Midi input because the user can simply
    	ignore messages in the buffer and close an input device at
    	any time.

    Before ¶

    Before :: proc "c" (t1, t2: Timestamp) -> b32 {…}

    Channel ¶

    Channel :: proc "c" (channel: i32) -> i32 {…}

    Close ¶

    Close :: proc "c" (stream: Stream) -> Error ---


    	Close() closes a midi stream, flushing any pending buffers.
    	(PortMidi attempts to close open streams when the application 
    	exits -- this is particularly difficult under Windows.)

    CountDevices ¶

    CountDevices :: proc "c" () -> i32 ---

    Get devices count, ids range from 0 to CountDevices()-1.

    Dequeue ¶

    Dequeue :: proc "c" (queue: Queue, msg: rawptr) -> Error ---

    Dequeue() removes one item from the queue, copying it into msg.

    	Returns 1 if successful, and 0 if the queue is empty.
    	Returns .BufferOverflow if what would have been the next thing
    	in the queue was dropped due to overflow. (So when overflow occurs,
    	the receiver can receive a queue full of messages before getting the
    	overflow report. This protocol ensures that the reader will be 
    	notified when data is lost due to overflow.

    Enqueue ¶

    Enqueue :: proc "c" (queue: Queue, msg: rawptr) -> Error ---

    Enqueue() inserts one item into the queue, copying it from msg.

    	Returns .NoError if successful and .BufferOverflow if the queue was 
    	already full. If .BufferOverflow is returned, the overflow flag is set.

    GetDefaultInputDeviceID ¶

    GetDefaultInputDeviceID :: proc "c" () -> DeviceID ---

    GetDefaultOutputDeviceID ¶

    GetDefaultOutputDeviceID :: proc "c" () -> DeviceID ---

    GetDeviceInfo ¶

    GetDeviceInfo :: proc "c" (id: DeviceID) -> ^DeviceInfo ---


    	GetDeviceInfo() returns a pointer to a DeviceInfo structure
    	referring to the device specified by id.
    	If id is out of range the function returns nil.
    	The returned structure is owned by the PortMidi implementation and must
    	not be manipulated or freed. The pointer is guaranteed to be valid
    	between calls to Initialize() and Terminate().

    GetErrorText ¶

    GetErrorText :: proc(errnum: Error) -> string {…}

    Translate portmidi error number into human readable message. These strings are constants (set at compile time) so client has no need to allocate storage

    GetHostErrorText ¶

    GetHostErrorText :: proc(buf: []u8) -> string {…}

    Translate portmidi host error into human readable message. These strings are computed at run time, so client has to allocate storage. After this routine executes, the host error is cleared.

    HasHostError ¶

    HasHostError :: proc "c" (stream: Stream) -> b32 ---


    	Test whether stream has a pending host error. Normally, the client finds
    	out about errors through returned error codes, but some errors can occur
    	asynchronously where the client does not
    	explicitly call a function, and therefore cannot receive an error code.
    	The client can test for a pending error using HasHostError(). If true,
    	the error can be accessed and cleared by calling GetErrorText(). 
    	Errors are also cleared by calling other functions that can return
    	errors, e.g. OpenInput(), OpenOutput(), Read(), Write(). The
    	client does not need to call HasHostError(). Any pending error will be
    	reported the next time the client performs an explicit function call on 
    	the stream, e.g. an input or output operation. Until the error is cleared,
    	no new error codes will be obtained, even for a different stream.

    Initialize ¶

    Initialize :: proc "c" () -> Error ---


    	Initialize() is the library initialisation function - call this before
    	using the library.

    MessageCompose ¶

    MessageCompose :: MessageMake

    * MessageMake() encodes a short Midi message into a 32-bit word. If data1 and/or data2 are not present, use zero.

    MessageStatus(), MessageData1(), and MessageData2() extract fields from a 32-bit midi message.

    MessageData1 ¶

    MessageData1 :: proc "c" (msg: Message) -> i32 {…}

    MessageData2 ¶

    MessageData2 :: proc "c" (msg: Message) -> i32 {…}

    MessageDecompose ¶

    MessageDecompose :: proc "c" (msg: Message) -> (status: i32, data1, data2: i32) {…}

    MessageMake ¶

    MessageMake :: proc "c" (status: i32, data1, data2: i32) -> Message {…}

    * MessageMake() encodes a short Midi message into a 32-bit word. If data1 and/or data2 are not present, use zero.

    MessageStatus(), MessageData1(), and MessageData2() extract fields from a 32-bit midi message.

    MessageStatus ¶

    MessageStatus :: proc "c" (msg: Message) -> i32 {…}

    OpenInput ¶

    OpenInput :: proc "c" (
    	stream:          ^Stream, 
    	inputDevice:     DeviceID, 
    	inputDriverInfo: rawptr, 
    	bufferSize:      i32, 
    	time_proc:       TimeProc, 
    	time_info:       rawptr, 
    ) -> Error ---


    	OpenInput() and OpenOutput() open devices.
    	stream is the address of a Stream pointer which will receive
    	a pointer to the newly opened stream.
    	inputDevice is the id of the device used for input (see DeviceID above).
    	inputDriverInfo is a pointer to an optional driver specific data structure
    	containing additional information for device setup or handle processing.
    	inputDriverInfo is never required for correct operation. If not used
    	inputDriverInfo should be nil.
    	outputDevice is the id of the device used for output (see DeviceID above.)
    	outputDriverInfo is a pointer to an optional driver specific data structure
    	containing additional information for device setup or handle processing.
    	outputDriverInfo is never required for correct operation. If not used
    	outputDriverInfo should be nil.
    	For input, the buffersize specifies the number of input events to be 
    	buffered waiting to be read using Read(). For output, buffersize 
    	specifies the number of output events to be buffered waiting for output. 
    	(In some cases -- see below -- PortMidi does not buffer output at all
    	and merely passes data to a lower-level API, in which case buffersize
    	is ignored.)
    	latency is the delay in milliseconds applied to timestamps to determine 
    	when the output should actually occur. (If latency is < 0, 0 is assumed.) 
    	If latency is zero, timestamps are ignored and all output is delivered
    	immediately. If latency is greater than zero, output is delayed until the
    	message timestamp plus the latency. (NOTE: the time is measured relative 
    	to the time source indicated by time_proc. Timestamps are absolute,
    	not relative delays or offsets.) In some cases, PortMidi can obtain
    	better timing than your application by passing timestamps along to the
    	device driver or hardware. Latency may also help you to synchronize midi
    	data to audio data by matching midi latency to the audio buffer latency.
    	time_proc is a pointer to a procedure that returns time in milliseconds. It
    	may be nil, in which case a default millisecond timebase (PortTime) is 
    	used. If the application wants to use PortTime, it should start the timer
    	(call Pt_Start) before calling OpenInput or OpenOutput. If the
    	application tries to start the timer *after* OpenInput or OpenOutput,
    	it may get a ptAlreadyStarted error from Pt_Start, and the application's
    	preferred time resolution and callback function will be ignored.
    	time_proc result values are appended to incoming MIDI data, and time_proc
    	times are used to schedule outgoing MIDI data (when latency is non-zero).
    	time_info is a pointer passed to time_proc.
    	Example: If I provide a timestamp of 5000, latency is 1, and time_proc
    	returns 4990, then the desired output time will be when time_proc returns
    	timestamp+latency = 5001. This will be 5001-4990 = 11ms from now.
    	return value:
    	Upon success Open() returns NoError and places a pointer to a
    	valid Stream in the stream argument.
    	If a call to Open() fails a nonzero error code is returned (see
    	PMError above) and the value of port is invalid.
    	Any stream that is successfully opened should eventually be closed
    	by calling Close().

    OpenOutput ¶

    OpenOutput :: proc "c" (
    	stream:           ^Stream, 
    	outputDevice:     DeviceID, 
    	outputDriverInfo: rawptr, 
    	bufferSize:       i32, 
    	time_proc:        TimeProc, 
    	time_info:        rawptr, 
    	latency:          i32, 
    ) -> Error ---

    Poll ¶

    Poll :: proc "c" (stream: Stream) -> Error ---


    	Poll() tests whether input is available.

    QueueCreate ¶

    QueueCreate :: proc "c" (num_msgs: i32, bytes_per_msg: i32) -> Queue ---

    QueueDestroy ¶

    QueueDestroy :: proc "c" (queue: Queue) -> Error ---

    QueueEmpty ¶

    QueueEmpty :: proc "c" (queue: Queue) -> b32 ---

    QueueFull ¶

    QueueFull :: proc "c" (queue: Queue) -> b32 ---

    QueueFull() returns non-zero if the queue is full

        QueueEmpty() returns non-zero if the queue is empty
        Either condition may change immediately because a parallel
        enqueue or dequeue operation could be in progress. Furthermore,
        QueueEmpty() is optimistic: it may say false, when due to 
        out-of-order writes, the full message has not arrived. Therefore,
        Dequeue() could still return 0 after QueueEmpty() returns
        false. On the other hand, QueueFull() is pessimistic: if it
        returns false, then Enqueue() is guaranteed to succeed. 
        Error conditions: QueueFull() returns .BadPtr if queue is nil.
        QueueEmpty() returns false if queue is nil.

    QueuePeek ¶

    QueuePeek :: proc "c" (queue: Queue) -> rawptr ---

    QueuePeek() returns a pointer to the item at the head of the queue,

    	or NULL if the queue is empty. The item is not removed from the queue.
    	QueuePeek() will not indicate when an overflow occurs. If you want
    	to get and check .BufferOverflow messages, use the return value of
    	QueuePeek() *only* as an indication that you should call 
    	Dequeue(). At the point where a direct call to Dequeue() would
    	return .BufferOverflow, QueuePeek() will return NULL but internally
    	clear the .BufferOverflow flag, enabling Enqueue() to resume
    	enqueuing messages. A subsequent call to QueuePeek()
    	will return a pointer to the first message *after* the overflow. 
    	Using this as an indication to call Dequeue(), the first call
    	to Dequeue() will return .BufferOverflow. The second call will
    	return success, copying the same message pointed to by the previous
    	When to use QueuePeek(): (1) when you need to look at the message
    	data to decide who should be called to receive it. (2) when you need
    	to know a message is ready but cannot accept the message.
    	Note that QueuePeek() is not a fast check, so if possible, you 
    	might as well just call Dequeue() and accept the data if it is there.

    Read ¶

    Read :: proc "c" (stream: Stream, buffer: [^]Event, length: i32) -> i32 ---


    	Read() retrieves midi data into a buffer, and returns the number
    	of events read. Result is a non-negative number unless an error occurs, 
    	in which case a Error value will be returned.
    	Buffer Overflow
    	The problem: if an input overflow occurs, data will be lost, ultimately 
    	because there is no flow control all the way back to the data source. 
    	When data is lost, the receiver should be notified and some sort of 
    	graceful recovery should take place, e.g. you shouldn't resume receiving 
    	in the middle of a long sysex message.
    	With a lock-free fifo, which is pretty much what we're stuck with to 
    	enable portability to the Mac, it's tricky for the producer and consumer 
    	to synchronously reset the buffer and resume normal operation.
    	Solution: the buffer managed by PortMidi will be flushed when an overflow
    	occurs. The consumer (Read()) gets an error message (.BufferOverflow)
    	and ordinary processing resumes as soon as a new message arrives. The
    	remainder of a partial sysex message is not considered to be a "new
    	message" and will be flushed as well.

    SetChannelMask ¶

    SetChannelMask :: proc "c" (stream: Stream, mask: i32) -> Error ---


    	SetChannelMask() filters incoming messages based on channel.
    	The mask is a 16-bit bitfield corresponding to appropriate channels.
    	The _Channel macro can assist in calling this function.
    	i.e. to set receive only input on channel 1, call with
    	Multiple channels should be OR'd together, like
    	SetChannelMask(Channel(10) | Channel(11))
    	Note that channels are numbered 0 to 15 (not 1 to 16). Most 
    	synthesizer and interfaces number channels starting at 1, but
    	PortMidi numbers channels starting at 0.
    	All channels are allowed by default

    SetFilter ¶

    SetFilter :: proc "c" (stream: Stream, filters: i32) -> Error ---


    	SetFilter() sets filters on an open input stream to drop selected
    	input types. By default, only active sensing messages are filtered.
    	To prohibit, say, active sensing and sysex messages, call
    	SetFilter(stream, FILT_ACTIVE | FILT_SYSEX);
    	Filtering is useful when midi routing or midi thru functionality is being
    	provided by the user application.
    	For example, you may want to exclude timing messages (clock, MTC, start/stop/continue),
    	while allowing note-related messages to pass.
    	Or you may be using a sequencer or drum-machine for MIDI clock information but want to
    	exclude any notes it may play.

    SetOverflow ¶

    SetOverflow :: proc "c" (queue: Queue) -> Error ---

    SetOverflow() allows the writer (enqueuer) to signal an overflow

    	condition to the reader (dequeuer). E.g. when transfering data from 
    	the OS to an application, if the OS indicates a buffer overrun,
    	SetOverflow() can be used to insure that the reader receives a
    	.BufferOverflow result from Dequeue(). Returns .BadPtr if queue
    	is NULL, returns .BufferOverflow if buffer is already in an overflow
    	state, returns .NoError if successfully set overflow state.

    Synchronize ¶

    Synchronize :: proc "c" (stream: Stream) -> Error ---


    	Synchronize() instructs PortMidi to (re)synchronize to the
    	time_proc passed when the stream was opened. Typically, this
    	is used when the stream must be opened before the time_proc
    	reference is actually advancing. In this case, message timing
    	may be erratic, but since timestamps of zero mean 
    	"send immediately," initialization messages with zero timestamps
    	can be written without a functioning time reference and without
    	problems. Before the first MIDI message with a non-zero
    	timestamp is written to the stream, the time reference must
    	begin to advance (for example, if the time_proc computes time
    	based on audio samples, time might begin to advance when an 
    	audio stream becomes active). After time_proc return values
    	become valid, and BEFORE writing the first non-zero timestamped 
    	MIDI message, call Synchronize() so that PortMidi can observe
    	the difference between the current time_proc value and its
    	MIDI stream time. 
    	In the more normal case where time_proc 
    	values advance continuously, there is no need to call 
    	Synchronize. PortMidi will always synchronize at the 
    	first output message and periodically thereafter.

    Terminate ¶

    Terminate :: proc "c" () -> Error ---


    	Terminate() is the library termination function - call this after
    	using the library.

    Write ¶

    Write :: proc "c" (stream: Stream, buffer: [^]Event, length: i32) -> Error ---

    Write() writes midi data from a buffer. This may contain:

    		- short messages 
    		- sysex messages that are converted into a sequence of Event
    		  structures, e.g. sending data from a file or forwarding them
    		  from midi input.
    	Use WriteSysEx() to write a sysex message stored as a contiguous 
    	array of bytes.
    	Sysex data may contain embedded real-time messages.

    WriteShort ¶

    WriteShort :: proc "c" (stream: Stream, whence: Timestamp, msg: Message) -> Error ---


    	WriteShort() writes a timestamped non-system-exclusive midi message.
    	Messages are delivered in order as received, and timestamps must be 
    	non-decreasing. (But timestamps are ignored if the stream was opened
    	with latency = 0.)

    WriteSysEx ¶

    WriteSysEx :: proc "c" (stream: Stream, whence: Timestamp, msg: cstring) -> Error ---


    	WriteSysEx() writes a timestamped system-exclusive midi message.

    Procedure Groups

    This section is empty.

    Source Files

    Generation Information

    Generated with odin version dev-2024-04 (vendor "odin") Windows_amd64 @ 2024-04-26 21:08:59.826576100 +0000 UTC