Struct PatternEvent

Namespace

SunSharp

Assembly

SunSharp.dll

Represents a SunVox pattern event that encodes music commands such as notes, effects, and controller changes in a compact 64-bit format.

[Serializable]
public struct PatternEvent

Remarks

For better readability, consider using the property accessors and factory methods provided.

Constructors

PatternEvent(byte, byte, ushort, byte, byte, ushort)

Initializes a pattern event with individual fields. Uses raw data format.

public PatternEvent(byte nn, byte vv, ushort mm, byte cc, byte ee, ushort xxyy)

Parameters

nn byte

Note number or special command. Consider using Note instead.

vv byte

Raw velocity value (actual velocity + 1). A value of 0 indicates default velocity should be used. Consider using Velocity property instead for automatic offset handling.

mm ushort

Raw module number (actual module ID + 1). A value of 0 indicates no module is targeted. Consider using ModuleId property instead for automatic offset handling.

cc byte

Raw controller number (high byte of CCEE, actual controller + 1). Consider using ControllerId property instead for automatic offset handling.

ee byte

Raw effect code (low byte of CCEE). Consider using Effect property instead for type-safe effect handling.

xxyy ushort

Combined 16-bit parameter value (low byte = XX, high byte = YY).

Remarks

Consider using factory methods for better readability.

PatternEvent(ulong)

Initializes a new instance of the PatternEvent struct from raw 64-bit data.

public PatternEvent(ulong value)

Parameters

value ulong

The raw 64-bit value containing all event fields.

Fields

PatternEventHeaderString

Column header string for pattern display: "NNVVMMMMCCEEXXYY".

public const string PatternEventHeaderString = "NNVVMMMMCCEEXXYY"

Field Value

string

Remarks

Primarily used for formatting pattern output in tracker-style displays.

Properties

CC

Raw controller number (high byte of CCEE, actual controller + 1). Consider using ControllerId property instead for automatic offset handling.

public byte CC { readonly get; set; }

Property Value

byte

CCEE

Combined controller and effect code as a 16-bit value (high byte = CC, low byte = EE). Consider using ControllerId and Effect properties instead for better readability.

public ushort CCEE { readonly get; set; }

Property Value

ushort

ControllerId

Controller identifier (0-based). Returns null when no controller is specified. Module controllers: 0-126 (raw data: 1-127). MIDI controllers: 127+ (raw data: 0x80+). Automatically handles the +1 offset used in raw data.

public byte? ControllerId { readonly get; set; }

Property Value

byte?

Data

Raw 64-bit data representing the entire event.

public ulong Data { readonly get; set; }

Property Value

ulong

EE

Raw effect code (low byte of CCEE). Consider using Effect property instead for type-safe effect handling.

public byte EE { readonly get; set; }

Property Value

byte

Effect

Pattern event effect code.

public Effect Effect { readonly get; set; }

Property Value

Effect

Empty

Gets an empty pattern event with all fields set to zero (represents a blank pattern cell).

public static PatternEvent Empty { get; }

Property Value

PatternEvent

HasController

Gets a value indicating whether this event contains a controller change.

public readonly bool HasController { get; }

Property Value

bool

HasEffect

Gets a value indicating whether this event contains an effect command.

public readonly bool HasEffect { get; }

Property Value

bool

HasModule

Gets a value indicating whether this event targets a specific module.

public readonly bool HasModule { get; }

Property Value

bool

HasNote

Gets a value indicating whether this event contains a note command (musical note or special command).

public readonly bool HasNote { get; }

Property Value

bool

HasValue

Gets a value indicating whether this event contains a non-zero parameter value.

public readonly bool HasValue { get; }

Property Value

bool

HasVelocity

Gets a value indicating whether this event contains an explicit velocity value (not using default).

public readonly bool HasVelocity { get; }

Property Value

bool

IsEmpty

Whether this is an empty event (all fields zero).

public readonly bool IsEmpty { get; }

Property Value

bool

MM

Raw module number (actual module ID + 1). A value of 0 indicates no module is targeted. Consider using ModuleId property instead for automatic offset handling.

public ushort MM { readonly get; set; }

Property Value

ushort

ModuleId

Module identifier (0-based). Returns null when no module is specified. Automatically handles the +1 offset used in raw data.

public int? ModuleId { readonly get; set; }

Property Value

int?

NN

Note number or special command. Consider using Note instead.

public byte NN { readonly get; set; }

Property Value

byte

Note

Note value. Allows for explicit note commands.

public Note Note { readonly get; set; }

Property Value

Note

VV

Raw velocity value (actual velocity + 1). A value of 0 indicates default velocity should be used. Consider using Velocity property instead for automatic offset handling.

public byte VV { readonly get; set; }

Property Value

byte

Value

Parameter value for controller or effect (16-bit unsigned integer).

Range: 0-32768 (0x8000) for controllers, 0-65535 (0xFFFF) for effects.

For pitch commands: 0x0000 = highest pitch, 0x7800 = C0, 0x100 = one semitone.

public ushort Value { readonly get; set; }

Property Value

ushort

Velocity

Note velocity. Returns null when default velocity is used. Automatically handles the +1 offset used in raw data.

public byte? Velocity { readonly get; set; }

Property Value

byte?

XX

Low byte of parameter value (lower 8 bits of XXYY).

public byte XX { readonly get; set; }

Property Value

byte

XXYY

Combined 16-bit parameter value (low byte = XX, high byte = YY).

public ushort XXYY { readonly get; set; }

Property Value

ushort

YY

High byte of parameter value (upper 8 bits of XXYY).

public byte YY { readonly get; set; }

Property Value

byte

Methods

ControllerEvent(int, byte, ushort)

Creates a controller event that changes a module parameter.

public static PatternEvent ControllerEvent(int moduleId, byte controller, ushort value)

Parameters

moduleId int

Module identifier (0-based). Returns null when no module is specified. Automatically handles the +1 offset used in raw data.

controller byte

Controller identifier (0-based). Returns null when no controller is specified. Module controllers: 0-126 (raw data: 1-127). MIDI controllers: 127+ (raw data: 0x80+). Automatically handles the +1 offset used in raw data.

value ushort

Parameter value for controller or effect (16-bit unsigned integer).

Range: 0-32768 (0x8000) for controllers, 0-65535 (0xFFFF) for effects.

For pitch commands: 0x0000 = highest pitch, 0x7800 = C0, 0x100 = one semitone.

Returns

PatternEvent

Remarks

For better type safety and readability, consider using typed module handles and extension methods.

EffectEvent(int?, Effect, ushort)

Creates an effect event that applies a pattern effect.

public static PatternEvent EffectEvent(int? moduleId, Effect effect, ushort value)

Parameters

moduleId int?

Module identifier (0-based). Returns null when no module is specified. Automatically handles the +1 offset used in raw data.

effect Effect

Pattern event effect code.

value ushort

Parameter value for controller or effect (16-bit unsigned integer).

Range: 0-32768 (0x8000) for controllers, 0-65535 (0xFFFF) for effects.

For pitch commands: 0x0000 = highest pitch, 0x7800 = C0, 0x100 = one semitone.

Returns

PatternEvent

A new PatternEvent configured as an effect event.

Equals(PatternEvent)

Indicates whether the current object is equal to another object of the same type.

public readonly bool Equals(PatternEvent other)

Parameters

other PatternEvent

An object to compare with this object.

Returns

bool

true if the current object is equal to the other parameter; otherwise, false.

Equals(object?)

Indicates whether this instance and a specified object are equal.

public override readonly bool Equals(object? obj)

Parameters

obj object

The object to compare with the current instance.

Returns

bool

true if obj and this instance are the same type and represent the same value; otherwise, false.

GetHashCode()

Returns the hash code for this instance.

public override readonly int GetHashCode()

Returns

int

A 32-bit signed integer that is the hash code for this instance.

Merge(PatternEvent, PatternEvent)

Merges two events, with non-zero values from second overwriting corresponding values in first.

public static PatternEvent Merge(PatternEvent first, PatternEvent second)

Parameters

first PatternEvent

The base event providing default values.

second PatternEvent

The event whose non-zero fields override the base event.

Returns

PatternEvent

A merged PatternEvent combining both inputs.

Remarks

This performs a field-by-field merge where any non-zero field in second replaces the corresponding field in first. Useful for layering pattern data or applying partial updates.

NewEvent(Note, byte?, int?, byte?, Effect, ushort)

Creates a new generic pattern event with optional parameters for flexible event construction.

public static PatternEvent NewEvent(Note note = default, byte? velocity = null, int? moduleId = null, byte? controller = null, Effect effect = Effect.None, ushort value = 0)

Parameters

note Note

Note value. Allows for explicit note commands.

velocity byte?

Note velocity. Returns null when default velocity is used. Automatically handles the +1 offset used in raw data.

moduleId int?

Module identifier (0-based). Returns null when no module is specified. Automatically handles the +1 offset used in raw data.

controller byte?

Controller identifier (0-based). Returns null when no controller is specified. Module controllers: 0-126 (raw data: 1-127). MIDI controllers: 127+ (raw data: 0x80+). Automatically handles the +1 offset used in raw data.

effect Effect

Pattern event effect code.

value ushort

Parameter value for controller or effect (16-bit unsigned integer).

Range: 0-32768 (0x8000) for controllers, 0-65535 (0xFFFF) for effects.

For pitch commands: 0x0000 = highest pitch, 0x7800 = C0, 0x100 = one semitone.

Returns

PatternEvent

A new PatternEvent with the specified fields.

Remarks

This method provides maximum flexibility for creating events. For common scenarios, consider using specific factory methods like NoteEvent(Note, int?, byte?), ControllerEvent(int, byte, ushort), etc.

NoteEvent(Note, int?, byte?)

Creates a note event that triggers a note on the specified module.

public static PatternEvent NoteEvent(Note note, int? moduleId, byte? velocity = null)

Parameters

note Note

Note value. Allows for explicit note commands.

moduleId int?

Module identifier (0-based). Returns null when no module is specified. Automatically handles the +1 offset used in raw data.

velocity byte?

Note velocity. Returns null when default velocity is used. Automatically handles the +1 offset used in raw data.

Returns

PatternEvent

SetFrequencyEvent(int, double, byte?)

Creates a Set Pitch event by converting a frequency in Hz to the appropriate pitch value.

public static PatternEvent SetFrequencyEvent(int moduleId, double frequency, byte? velocity = null)

Parameters

moduleId int

Module number (0-based).

frequency double

Frequency in Hz (e.g., 440.0 for A4).

velocity byte?

Velocity value (0-128). Use null for default velocity.

Returns

PatternEvent

A new PatternEvent with the calculated pitch value.

Examples

// Set pitch to A4 (440 Hz)
var a440 = PatternEvent.SetFrequencyEvent(0, 440.0, 100);
// Set pitch to middle C (261.63 Hz)
var c4 = PatternEvent.SetFrequencyEvent(0, 261.63);

SetPitchEvent(int, ushort, byte?)

Creates a Set Pitch event with exact pitch value for microtonal or pitch-bend effects.

public static PatternEvent SetPitchEvent(int moduleId, ushort pitch, byte? velocity = null)

Parameters

moduleId int

Module number (0-based).

pitch ushort

Pitch value where 0x0000 = highest pitch, 0x7800 = C0 (lowest), 0x100 = one semitone.

velocity byte?

Velocity value (0-128). Use null for default velocity.

Returns

PatternEvent

A new PatternEvent configured as a set pitch event.

Examples

// Set pitch to middle C (C4 = 0x3C00)
var middleC = PatternEvent.SetPitchEvent(0, 0x3C00);
// Set pitch to A4 (440Hz reference = 0x4500)
var a440 = PatternEvent.SetPitchEvent(0, 0x4500, 100);

ToString()

Returns hexadecimal string representation that roughly follows the SunVox format. Empty fields shown as spaces.

public override readonly string ToString()

Returns

string

Remarks

Some examples of the output format:

• "C4__00001________" - Note C4 on module 0, no velocity, no effect/controller/value.
• "__64__0001_02_1000" - Velocity 100 on module 0, controller 2 set to 4096.

Keep in mind:

• Module number (MMMM) is as displayed in SunVox, incremented by one compared to library-side module IDs
• CC and EE are independent, unlike in SunVox
• CC is as displayed in SunVox, incremented by one compared to library-side module IDs

Note: spaces were replaced with underscores for better visibility in the examples.

Operators

operator ==(PatternEvent, PatternEvent)

public static bool operator ==(PatternEvent a, PatternEvent b)

Parameters

a PatternEvent

b PatternEvent

Returns

bool

implicit operator ulong(PatternEvent)

public static implicit operator ulong(PatternEvent @event)

Parameters

event PatternEvent

Returns

ulong

implicit operator PatternEvent(ulong)

public static implicit operator PatternEvent(ulong value)

Parameters

value ulong

Returns

PatternEvent

operator !=(PatternEvent, PatternEvent)

public static bool operator !=(PatternEvent a, PatternEvent b)

Parameters

a PatternEvent

b PatternEvent

Returns

bool