Module xSongPos
Describes a position within the project timeline .
Three options are designed to deal with song boundaries, pattern-loop and block-loop boundaries. By default, they are set to settings which mimic the behavior in Renoise when playing/manipulating the playback position:
self.boundsmode = xSongPos.OUTOFBOUNDS.LOOP self.loopboundary = xSongPos.LOOPBOUNDARY.SOFT self.blockboundary = xSongPos.BLOCK_BOUNDARY.SOFT
Functions
__init (pos) | constructor - create new position at the very least, you need to specify a table containing {sequence,line} |
get_pattern_index (seq_idx) | Static methods |
get_pattern_num_lines (seq_idx) | Retrieve the pattern index OPTIMIZE how to implement a caching mechanism? |
end_of_sequence_loop (seq_idx) | |
start_of_sequence_loop (seq_idx) | |
end_of_blockloop (line_idx) | check if line is equal to, or beyond end of block-loop |
start_of_blockloop (line_idx) | check if line is equal to, or before start of block-loop |
within_bounds (seq_idx, line_idx) | check if position is within actual song boundaries |
get_line_diff (pos1, pos2) | |
increase_by_lines (num_lines) | increase the position by X number of lines |
decrease_by_lines (num_lines) | subtract a number of lines from position |
enforce_boundary (direction, seq_idx, line_idx) | restrict the position to boundaries (sequence, loop) |
enforce_block_boundary (direction, line_idx, line_delta) | restrict the position to boundaries (block-loop) |
next_beat () | return the next beat position |
next_bar () | return the next bar position |
next_block () | return the next block position |
next_pattern () | return the beginning of next pattern |
Tables
OUT_OF_BOUNDS | How to deal with sequence (song) boundaries CAP: do not exceed, cap at beginning/end LOOP: going past the end will take us to the start, and vice versa NULL: going past the end or start will return nil |
LOOP_BOUNDARY | How to deal with loop boundaries HARD: always stay within loop, no matter the position SOFT: only stay within loop when playback takes us there NONE: continue past loop boundary (ignore) |
BLOCK_BOUNDARY | How to deal with block-loop boundaries HARD: always stay within loop, no matter the position SOFT: only stay within loop when playback takes us there NONE: continue past loop boundary (ignore) |
Fields
self.sequence | position in the pattern sequence. |
self.line | position in the pattern at the given pattern sequence. |
self.lines_travelled | int, travelled distance (in lines) note: this is not reliable unless you are (exclusively) using the increase/decrease methods to control the position! |
self.bounds_mode | xSongPos.OUTOFBOUNDS, deal with sequence (song) boundaries |
self.loop_boundary | xSongPos.LOOP_BOUNDARY, deals with patt-loop boundaries |
self.block_boundary | xSongPos.BLOCK_BOUNDARY, deals with block-loop boundaries |
Functions
- __init (pos)
-
constructor - create new position
at the very least, you need to specify a table containing {sequence,line}
Parameters:
- pos [opt] (renoise.SongPos, xSongPos or {sequence,line} )
- get_pattern_index (seq_idx)
-
Static methods Retrieve the pattern index while respecting the OUTOFBOUNDS mode
Parameters:
- seq_idx , sequence index
Returns:
-
int or nil
- get_pattern_num_lines (seq_idx)
-
Retrieve the pattern index
OPTIMIZE how to implement a caching mechanism?
Parameters:
- seq_idx , sequence index
Returns:
- int or nil
- int, sequence index or nil
- end_of_sequence_loop (seq_idx)
-
Parameters:
- seq_idx , sequence index
Returns:
- int, sequence index or nil
- int, sequence index or nil
- start_of_sequence_loop (seq_idx)
-
Parameters:
- seq_idx , sequence index
Returns:
-
int, sequence index or nil
- end_of_blockloop (line_idx)
-
check if line is equal to, or beyond end of block-loop
Parameters:
- line_idx , line index
Returns:
-
int, line index or nil
[[
- start_of_blockloop (line_idx)
-
check if line is equal to, or before start of block-loop
Parameters:
- line_idx , line index
Returns:
-
int, line index or nil
- within_bounds (seq_idx, line_idx)
-
check if position is within actual song boundaries
Parameters:
- seq_idx , int
- line_idx , int
Returns:
- bool
- int
- get_line_diff (pos1, pos2)
-
Parameters:
- pos1 (SongPos)
- pos2 (SongPos)
Returns:
-
int
- increase_by_lines (num_lines)
-
increase the position by X number of lines
Parameters:
- num_lines
- decrease_by_lines (num_lines)
-
subtract a number of lines from position
Parameters:
- num_lines , int
- enforce_boundary (direction, seq_idx, line_idx)
-
restrict the position to boundaries (sequence, loop)
Parameters:
- direction , string ("increase" or "decrease")
- seq_idx , int
- line_idx , int
Returns:
-
sequence,line,done
sequence (int)
line (int)
done (bool), true when no further action needed (capped/nullified)
- enforce_block_boundary (direction, line_idx, line_delta)
-
restrict the position to boundaries (block-loop)
Parameters:
- direction , string ("increase" or "decrease")
- line_idx (int)
- line_delta (int), #lines to add/subtract, negative when decreasing
Returns:
-
line (int)
- next_beat ()
- return the next beat position
- next_bar ()
- return the next bar position
- next_block ()
- return the next block position
- next_pattern ()
- return the beginning of next pattern
Tables
- OUT_OF_BOUNDS
-
How to deal with sequence (song) boundaries
CAP: do not exceed, cap at beginning/end
LOOP: going past the end will take us to the start, and vice versa
NULL: going past the end or start will return nil
Fields:
- CAP
- LOOP
- NULL
- LOOP_BOUNDARY
-
How to deal with loop boundaries
HARD: always stay within loop, no matter the position
SOFT: only stay within loop when playback takes us there
NONE: continue past loop boundary (ignore)
Fields:
- HARD
- SOFT
- NONE
- BLOCK_BOUNDARY
-
How to deal with block-loop boundaries
HARD: always stay within loop, no matter the position
SOFT: only stay within loop when playback takes us there
NONE: continue past loop boundary (ignore)
Fields:
- HARD
- SOFT
- NONE
Fields
- self.sequence
- position in the pattern sequence. TODO make property
- self.line
- position in the pattern at the given pattern sequence. TODO make property
- self.lines_travelled
- int, travelled distance (in lines) note: this is not reliable unless you are (exclusively) using the increase/decrease methods to control the position!
- self.bounds_mode
- xSongPos.OUTOFBOUNDS, deal with sequence (song) boundaries
- self.loop_boundary
- xSongPos.LOOP_BOUNDARY, deals with patt-loop boundaries
- self.block_boundary
- xSongPos.BLOCK_BOUNDARY, deals with block-loop boundaries