AgsNotation: Advanced Gtk+ Sequencer Audio Reference Manual

AgsNotation

AgsNotation — Notation class supporting selection and clipboard

Stability Level

Stable, unless otherwise indicated

Functions

#define	AGS_NOTATION_GET_OBJ_MUTEX()
GRecMutex *	ags_notation_get_obj_mutex ()
gboolean	ags_notation_test_flags ()
void	ags_notation_set_flags ()
void	ags_notation_unset_flags ()
GList *	ags_notation_find_near_timestamp ()
GList *	ags_notation_add ()
gint	ags_notation_sort_func ()
GObject *	ags_notation_get_audio ()
void	ags_notation_set_audio ()
guint	ags_notation_get_audio_channel ()
void	ags_notation_set_audio_channel ()
gboolean	ags_notation_get_is_minor ()
void	ags_notation_set_is_minor ()
guint	ags_notation_get_sharp_flats ()
void	ags_notation_set_sharp_flats ()
AgsTimestamp *	ags_notation_get_timestamp ()
void	ags_notation_set_timestamp ()
GList *	ags_notation_get_note ()
void	ags_notation_set_note ()
void	ags_notation_add_note ()
void	ags_notation_remove_note ()
gboolean	ags_notation_remove_note_at_position ()
GList *	ags_notation_get_selection ()
gboolean	ags_notation_is_note_selected ()
AgsNote *	ags_notation_find_point ()
GList *	ags_notation_find_region ()
GList *	ags_notation_find_offset ()
GList *	ags_notation_find_note_256th_range ()
void	ags_notation_free_selection ()
void	ags_notation_free_all_selection ()
void	ags_notation_add_point_to_selection ()
void	ags_notation_remove_point_from_selection ()
void	ags_notation_add_region_to_selection ()
void	ags_notation_remove_region_from_selection ()
void	ags_notation_add_all_to_selection ()
xmlNode *	ags_notation_copy_selection ()
xmlNode *	ags_notation_cut_selection ()
void	ags_notation_insert_from_clipboard ()
void	ags_notation_insert_from_clipboard_extended ()
guchar *	ags_notation_to_raw_midi ()
AgsNotation *	ags_notation_from_raw_midi ()
AgsNotation *	ags_notation_new ()

Properties

AgsAudio *	audio	Read / Write
guint	audio-channel	Read / Write
gpointer	note	Read / Write
AgsTimestamp *	timestamp	Read / Write

Types and Values

#define	AGS_NOTATION_DEFAULT_BPM
#define	AGS_NOTATION_TICS_PER_BEAT
#define	AGS_NOTATION_MINIMUM_NOTE_LENGTH
#define	AGS_NOTATION_MAXIMUM_NOTE_LENGTH
#define	AGS_NOTATION_DEFAULT_LENGTH
#define	AGS_NOTATION_DEFAULT_JIFFIE
#define	AGS_NOTATION_DEFAULT_DURATION
#define	AGS_NOTATION_DEFAULT_OFFSET
#define	AGS_NOTATION_DEFAULT_END
#define	AGS_NOTATION_DEFAULT_DIVISION
#define	AGS_NOTATION_CLIPBOARD_VERSION
#define	AGS_NOTATION_CLIPBOARD_TYPE
#define	AGS_NOTATION_CLIPBOARD_FORMAT
enum	AgsNotationFlags

Object Hierarchy

    GFlags
    ╰── AgsNotationFlags
    GObject
    ╰── AgsNotation

Includes

#include <ags/audio/ags_notation.h>

Description

AgsNotation acts as a container of AgsNote. The timestamp property tells the engine what the first x offset of AgsNote applies.

You can lookup AgsNotation by start x offset with ags_notation_find_near_timestamp(). The next x offset is calculated as following:

next_x_offset = x_offset + AGS_NOTATION_DEFAULT_OFFSET;

Use ags_notation_add_note() to add AgsNote to AgsNotation and ags_notation_remove_note() to remove it again.

In order to copy or cut notes you select them first by calling ags_notation_add_region_to_selection().

Functions

AGS_NOTATION_GET_OBJ_MUTEX()

#define AGS_NOTATION_GET_OBJ_MUTEX(obj) (&(((AgsNotation *) obj)->obj_mutex))

ags_notation_get_obj_mutex ()

GRecMutex *
ags_notation_get_obj_mutex (AgsNotation *notation);

Get object mutex.

Parameters

notation

the AgsNotation

Returns

the GRecMutex to lock notation

Since: 3.1.0

ags_notation_test_flags ()

gboolean
ags_notation_test_flags (AgsNotation *notation,
                         AgsNotationFlags flags);

Test flags to be set on notation .

Parameters

notation	the AgsNotation
flags	the flags

Returns

TRUE if flags are set, else FALSE

Since: 3.0.0

ags_notation_set_flags ()

void
ags_notation_set_flags (AgsNotation *notation,
                        AgsNotationFlags flags);

Set flags on notation .

Parameters

notation	the AgsNotation
flags	the flags

Since: 3.0.0

ags_notation_unset_flags ()

void
ags_notation_unset_flags (AgsNotation *notation,
                          AgsNotationFlags flags);

Unset flags on notation .

Parameters

notation	the AgsNotation
flags	the flags

Since: 3.0.0

ags_notation_find_near_timestamp ()

GList *
ags_notation_find_near_timestamp (GList *notation,
                                  guint audio_channel,
                                  AgsTimestamp *timestamp);

Retrieve appropriate notation for timestamp.

Parameters

notation	the GList containing AgsNotation.	[element-type AgsAudio.Notation][transfer none]
audio_channel	the matching audio channel
timestamp	the matching timestamp, or `NULL` to match any timestamp.	[allow-none]

Returns

Next matching GList or NULL if not found.

[element-type AgsAudio.Notation][transfer none]

Since: 3.0.0

ags_notation_add ()

GList *
ags_notation_add (GList *notation,
                  AgsNotation *new_notation);

Add new_notation sorted to notation

Parameters

notation	the GList containing AgsNotation.	[element-type AgsAudio.Notation][transfer none]
new_notation	the AgsNotation to add

Returns

the new beginning of notation .

[element-type AgsAudio.Notation][transfer none]

Since: 3.0.0

ags_notation_sort_func ()

gint
ags_notation_sort_func (gconstpointer a,
                        gconstpointer b);

Compare a and b .

Parameters

a	the AgsNotation
b	another AgsNotation

Returns

0 if equal, -1 if smaller and 1 if bigger timestamp

Since: 3.0.0

ags_notation_get_audio ()

GObject *
ags_notation_get_audio (AgsNotation *notation);

Get audio.

Parameters

notation

the AgsNotation

Returns

the AgsAudio.

[transfer full]

Since: 3.1.0

ags_notation_set_audio ()

void
ags_notation_set_audio (AgsNotation *notation,
                        GObject *audio);

Set audio.

Parameters

notation	the AgsNotation
audio	the AgsAudio

Since: 3.1.0

ags_notation_get_audio_channel ()

guint
ags_notation_get_audio_channel (AgsNotation *notation);

Gets audio channel.

Parameters

notation

the AgsNotation

Returns

the audio channel

Since: 3.1.0

ags_notation_set_audio_channel ()

void
ags_notation_set_audio_channel (AgsNotation *notation,
                                guint audio_channel);

Sets audio channel.

Parameters

notation	the AgsNotation
audio_channel	the audio channel

Since: 3.1.0

ags_notation_get_is_minor ()

gboolean
ags_notation_get_is_minor (AgsNotation *notation);

Gets is minor.

Parameters

notation

the AgsNotation

Returns

is minor

Since: 3.1.0

ags_notation_set_is_minor ()

void
ags_notation_set_is_minor (AgsNotation *notation,
                           gboolean is_minor);

Sets is minor.

Parameters

notation	the AgsNotation
is_minor	is minor

Since: 3.1.0

ags_notation_get_sharp_flats ()

guint
ags_notation_get_sharp_flats (AgsNotation *notation);

Gets sharp flats.

Parameters

notation

the AgsNotation

Returns

the sharp flats

Since: 3.1.0

ags_notation_set_sharp_flats ()

void
ags_notation_set_sharp_flats (AgsNotation *notation,
                              guint sharp_flats);

Sets sharp flats.

Parameters

notation	the AgsNotation
sharp_flats	the sharp flats

Since: 3.1.0

ags_notation_get_timestamp ()

AgsTimestamp *
ags_notation_get_timestamp (AgsNotation *notation);

Get timestamp.

Parameters

notation

the AgsNotation

Returns

the AgsTimestamp.

[transfer full]

Since: 3.1.0

ags_notation_set_timestamp ()

void
ags_notation_set_timestamp (AgsNotation *notation,
                            AgsTimestamp *timestamp);

Set timestamp.

Parameters

notation	the AgsNotation
timestamp	the AgsTimestamp

Since: 3.1.0

ags_notation_get_note ()

GList *
ags_notation_get_note (AgsNotation *notation);

Get note.

Parameters

notation

the AgsNotation

Returns

the GList containig AgsNote.

[element-type AgsAudio.Note][transfer full]

Since: 3.1.0

ags_notation_set_note ()

void
ags_notation_set_note (AgsNotation *notation,
                       GList *note);

Set note by replacing existing.

Parameters

notation	the AgsNotation
note	the GList containing AgsNote.	[element-type AgsAudio.Note][transfer full]

Since: 3.1.0

ags_notation_add_note ()

void
ags_notation_add_note (AgsNotation *notation,
                       AgsNote *note,
                       gboolean use_selection_list);

Adds note to notation .

Parameters

notation	the AgsNotation
note	the AgsNote to add
use_selection_list	if `TRUE` add to selection, else to default notation

Since: 3.0.0

ags_notation_remove_note ()

void
ags_notation_remove_note (AgsNotation *notation,
                          AgsNote *note,
                          gboolean use_selection_list);

Removes note from notation .

Parameters

notation	the AgsNotation
note	the AgsNote to remove
use_selection_list	if `TRUE` remove from selection, else from default notation

Since: 3.0.0

ags_notation_remove_note_at_position ()

gboolean
ags_notation_remove_note_at_position (AgsNotation *notation,
                                      guint x,
                                      guint y);

Removes one AgsNote of notation.

Parameters

notation	the AgsNotation
x	offset
y	note

Returns

TRUE if successfully removed note.

Since: 3.0.0

ags_notation_get_selection ()

GList *
ags_notation_get_selection (AgsNotation *notation);

Retrieve selection.

Parameters

notation

the AgsNotation

Returns

the selection.

[element-type AgsAudio.Note][transfer none]

Since: 3.0.0

ags_notation_is_note_selected ()

gboolean
ags_notation_is_note_selected (AgsNotation *notation,
                               AgsNote *note);

Check selection for note.

Parameters

notation	the AgsNotation
note	the AgsNote to check for

Returns

TRUE if selected otherwise FALSE

Since: 3.0.0

ags_notation_find_point ()

AgsNote *
ags_notation_find_point (AgsNotation *notation,
                         guint x,
                         guint y,
                         gboolean use_selection_list);

Find note by offset and tone.

Parameters

notation	the AgsNotation
x	offset
y	note
use_selection_list	if `TRUE` selection is searched

Returns

the matching note.

[transfer none]

Since: 3.0.0

ags_notation_find_region ()

GList *
ags_notation_find_region (AgsNotation *notation,
                          guint x0,
                          guint y0,
                          guint x1,
                          guint y1,
                          gboolean use_selection_list);

Find note by offset and tone region.

Parameters

notation	the AgsNotation
x0	start offset
y0	start tone
x1	end offset
y1	end tone
use_selection_list	if `TRUE` selection is searched

Returns

the matching notes as GList.

[element-type AgsAudio.Note][transfer container]

Since: 3.0.0

ags_notation_find_offset ()

GList *
ags_notation_find_offset (AgsNotation *notation,
                          guint x,
                          gboolean use_selection_list);

Find all notes by offset x .

Parameters

notation	the AgsNotation
x	offset
use_selection_list	if `TRUE` selection is searched

Returns

the GList containing matching AgsNote.

[element-type AgsAudio.Note][transfer full]

Since: 3.0.0

ags_notation_find_note_256th_range ()

GList *
ags_notation_find_note_256th_range (AgsNotation *notation,
                                    guint x_256th_lower,
                                    guint x_256th_upper,
                                    gboolean use_selection_list);

Find all notes by range x_256th_lower to x_256th_upper .

Parameters

notation	the AgsNotation
x_256th_lower	offset lower
x_256th_upper	offset upper
use_selection_list	if `TRUE` selection is searched

Returns

the GList containing matching AgsNote.

[element-type AgsAudio.Note][transfer full]

Since: 6.9.0

ags_notation_free_selection ()

void
ags_notation_free_selection (AgsNotation *notation);

Clear selection.

Parameters

notation

the AgsNotation

Since: 3.0.0

ags_notation_free_all_selection ()

void
ags_notation_free_all_selection (GList *notation);

Clear all selection of notation .

Parameters

notation

the GList containing AgsNotation.

[element-type AgsAudio.Notation]

Since: 3.14.10

ags_notation_add_point_to_selection ()

void
ags_notation_add_point_to_selection (AgsNotation *notation,
                                     guint x,
                                     guint y,
                                     gboolean replace_current_selection);

Select notes at position.

Parameters

notation	the AgsNotation
x	x offset
y	y note tone
replace_current_selection	if `TRUE` selection is replaced

Since: 3.0.0

ags_notation_remove_point_from_selection ()

void
ags_notation_remove_point_from_selection
                               (AgsNotation *notation,
                                guint x,
                                guint y);

Remove notes at position of selection.

Parameters

notation	the AgsNotation
x	x offset
y	y note tone

Since: 3.0.0

ags_notation_add_region_to_selection ()

void
ags_notation_add_region_to_selection (AgsNotation *notation,
                                      guint x0,
                                      guint y0,
                                      guint x1,
                                      guint y1,
                                      gboolean replace_current_selection);

Add note within region to selection.

Parameters

notation	the AgsNotation
x0	x start offset
y0	y start tone
x1	x end offset
y1	y end tone
replace_current_selection	if `TRUE` selection is replaced

Since: 3.0.0

ags_notation_remove_region_from_selection ()

void
ags_notation_remove_region_from_selection
                               (AgsNotation *notation,
                                guint x0,
                                guint y0,
                                guint x1,
                                guint y1);

Remove note within region of selection.

Parameters

notation	the AgsNotation
x0	x start offset
y0	y start tone
x1	x end offset
y1	y end tone

Since: 3.0.0

ags_notation_add_all_to_selection ()

void
ags_notation_add_all_to_selection (AgsNotation *notation);

Add all note to selection.

Parameters

notation

the AgsNotation

Since: 3.0.0

ags_notation_copy_selection ()

xmlNode *
ags_notation_copy_selection (AgsNotation *notation);

Copy selection to clipboard.

Parameters

notation

the AgsNotation

Returns

the selection as XML.

[transfer none]

Since: 3.0.0

ags_notation_cut_selection ()

xmlNode *
ags_notation_cut_selection (AgsNotation *notation);

Cut selection to clipboard.

Parameters

notation

the AgsNotation

Returns

the selection as xmlNode.

[transfer none]

Since: 3.0.0

ags_notation_insert_from_clipboard ()

void
ags_notation_insert_from_clipboard (AgsNotation *notation,
                                    xmlNode *notation_node,
                                    gboolean reset_x_offset,
                                    guint x_offset,
                                    gboolean reset_y_offset,
                                    guint y_offset);

Paste previously copied notes.

Parameters

notation	the AgsNotation
notation_node	the clipboard XML data
reset_x_offset	if `TRUE` `x_offset` used as cursor
x_offset	region start cursor offset
reset_y_offset	if `TRUE` `y_offset` used as cursor
y_offset	region start cursor tone

Since: 3.0.0

ags_notation_insert_from_clipboard_extended ()

void
ags_notation_insert_from_clipboard_extended
                               (AgsNotation *notation,
                                xmlNode *notation_node,
                                gboolean reset_x_offset,
                                guint x_offset,
                                gboolean reset_y_offset,
                                guint y_offset,
                                gboolean match_channel,
                                gboolean no_duplicates);

Paste previously copied notes.

Parameters

notation	the AgsNotation
notation_node	the clipboard XML data
reset_x_offset	if `TRUE` `x_offset` used as cursor
x_offset	region start cursor offset
reset_y_offset	if `TRUE` `y_offset` used as cursor
y_offset	region start cursor tone
match_channel	only paste if channel matches
no_duplicates	only paste if current note doesn't exist

Since: 3.0.0

ags_notation_to_raw_midi ()

guchar *
ags_notation_to_raw_midi (AgsNotation *notation,
                          gdouble bpm,
                          gdouble delay_factor,
                          glong nn,
                          glong dd,
                          glong cc,
                          glong bb,
                          glong tempo,
                          guint *buffer_length);

Convert notation to raw-midi.

Parameters

notation	the AgsNotation
bpm	the source bpm
delay_factor	the source delay factor
nn	numerator
dd	denominator
cc	clocks
bb	beats
tempo	tempo
buffer_length	the return location of buffer length

Returns

the raw-midi buffer

Since: 3.0.0

ags_notation_from_raw_midi ()

AgsNotation *
ags_notation_from_raw_midi (guchar *raw_midi,
                            glong nn,
                            glong dd,
                            glong cc,
                            glong bb,
                            glong tempo,
                            gdouble bpm,
                            gdouble delay_factor,
                            guint buffer_length);

Parse raw_midi data and convert to AgsNotation.

Parameters

raw_midi	the data array
nn	numerator
dd	denominator
cc	clocks
bb	beats
tempo	tempo
bpm	the bpm to use
delay_factor	the segmentation delay factor
buffer_length	the buffer length

Returns

the AgsNotation.

[transfer full]

Since: 3.0.0

ags_notation_new ()

AgsNotation *
ags_notation_new (GObject *audio,
                  guint audio_channel);

Creates a new instance of AgsNotation.

Parameters

audio	the assigned AgsAudio
audio_channel	the audio channel to apply

Returns

the new AgsNotation

Since: 3.0.0

Types and Values

AGS_NOTATION_DEFAULT_BPM

#define AGS_NOTATION_DEFAULT_BPM (120.0)

AGS_NOTATION_TICS_PER_BEAT

#define AGS_NOTATION_TICS_PER_BEAT (1.0)

AGS_NOTATION_MINIMUM_NOTE_LENGTH

#define AGS_NOTATION_MINIMUM_NOTE_LENGTH (1.0 / 16.0)

AGS_NOTATION_MAXIMUM_NOTE_LENGTH

#define AGS_NOTATION_MAXIMUM_NOTE_LENGTH (16.0)

AGS_NOTATION_DEFAULT_LENGTH

#define AGS_NOTATION_DEFAULT_LENGTH (16 * 16 * 1200 / AGS_NOTATION_TICS_PER_BEAT)

AGS_NOTATION_DEFAULT_JIFFIE

#define AGS_NOTATION_DEFAULT_JIFFIE (60.0 / AGS_NOTATION_DEFAULT_BPM / AGS_NOTATION_TICS_PER_BEAT)

AGS_NOTATION_DEFAULT_DURATION

#define AGS_NOTATION_DEFAULT_DURATION (AGS_NOTATION_DEFAULT_LENGTH * AGS_NOTATION_DEFAULT_JIFFIE * AGS_USEC_PER_SEC)

AGS_NOTATION_DEFAULT_OFFSET

#define AGS_NOTATION_DEFAULT_OFFSET (64 * (1 / AGS_NOTATION_MINIMUM_NOTE_LENGTH))

AGS_NOTATION_DEFAULT_END

#define AGS_NOTATION_DEFAULT_END (64 * 64 * 1200)

AGS_NOTATION_DEFAULT_DIVISION

#define AGS_NOTATION_DEFAULT_DIVISION (96)

AGS_NOTATION_CLIPBOARD_VERSION

#define AGS_NOTATION_CLIPBOARD_VERSION "6.1.0"

AGS_NOTATION_CLIPBOARD_TYPE

#define AGS_NOTATION_CLIPBOARD_TYPE "AgsNotationClipboardXml"

AGS_NOTATION_CLIPBOARD_FORMAT

#define AGS_NOTATION_CLIPBOARD_FORMAT "AgsNotationNativePiano"

enum AgsNotationFlags

Enum values to control the behavior or indicate internal state of AgsNotation by enable/disable as flags.

Members

AGS_NOTATION_PATTERN_MODE	pattern mode
AGS_NOTATION_BYPASS	ignore any notation data

Property Details

The `“audio”` property

  “audio”                    AgsAudio *

The assigned AgsAudio

Owner: AgsNotation

Flags: Read / Write

Since: 3.0.0

The `“audio-channel”` property

  “audio-channel”            guint

The effect's audio-channel.

Owner: AgsNotation

Flags: Read / Write

Allowed values: <= 65535

Default value: 0

Since: 3.0.0

The `“note”` property

  “note”                     gpointer

The assigned AgsNote

[transfer full]

Owner: AgsNotation

Flags: Read / Write

Since: 3.0.0

The `“timestamp”` property

  “timestamp”                AgsTimestamp *

The notation's timestamp.

Owner: AgsNotation

Flags: Read / Write

Since: 3.0.0