Uhm, what would be the use case here?

I'd rather see this aspect to be factored into the already planned tick-boundary accurate playback.

I can see use cases like OpenMPT's smooth pattern scrolling - depending on the next play position, you may have to scroll either up or down.

Another use case is any general monitoring of pattern transitions. Let's say you want to do a transition to a different pattern once the current pattern has finished playing. Since the pattern may end on any row due to pattern break commands, it may not be known what is going to be the last row of the current pattern. If you want to solve this using tick-boundary rendering, you will have to throw away rendered audio for at least one tick, which I think would generally make control flow more complicated (and of course increase the required processing time).

Another use case is any general monitoring of pattern transitions. Let's say you want to do a transition to a different pattern once the current pattern has finished playing. Since the pattern may end on any row due to pattern break commands, it may not be known what is going to be the last row of the current pattern.

In that case, the required API would be more narrow than what is required to solve this issue. It would only be necessary to query the next play position after a tick has been rendered completely. And I would be very much OK with an API only implementing exactly that (once we have tick-boundary rendering).

I am very hesitant to add an API like the one described in this issue as it (on the API level) requires predicting the future. After all, semantically, the next play position does not actually need to be known until after the current tick has been rendered completely. It may be possible to implement that unambiguously for the currently known and supported formats, but if some other format or tracker quirk shows up that makes the next play position depending on anything mixer-related (sample loops or whatever), this API would not be supportable without adding another buffering or prediction layer inside libopenmpt.

I do not think it makes much sense to try to handle any of the use cases described here while not thinking about tick-boundary rendering at the same time.

Related: It might make sense to provide two more functions,

• get_current_tick(): Returns the currently processed tick on the current row.
• get_ticks_on_current_row(): Some pattern commands can extend the duration of a row and are not considered by get_current_speed(). This function would return the true number of ticks on the current row.

To summarize the additional design suggestions so far:

• set_tick_auto_advance(bool): Set tick-auto-advance mode, true meaning the default and old behaviour, false requiring manual tock advancing
• get_tick_auto_advance(): Getter for the above setting
• get_current_tick_frames(): Returns the number of sample frames in the current tick
• get_current_tick_remaining_frames(): Returns the number of sample frames until the current tick is done (this maps 1:1 to the internal m_PlayState.m_nBufferCount value)
• advance_tick(): Advances the internal play state by one tick. This would only be valid when get_current_tick_remaining_frames() == 0.
  This is by no means meant to be the final API design, but merely a suggestion for further discussion.
  How to handle read() in tick-boundary mode still has to be designed.
  Also, most of the API goes somewhat haywire when considering changing sample rates (which probably were not that good of a design decision in the first place). We might just deprecate changing sample rates and require explicit sample rate setting when desiring a change. However, the even more concerning (future) feature in this area is internal mixer oversampling and the inherent delay it would cause in the output path.

We also should investigate whether splitting advance_tick() into finish_tick() and start_tick() (or similar) could turn out to be useful for certain use cases.

One challenge here is going to be that, from what I understand, information like get_current_tick_frames() needs to be available before the actual read() call, but currently this information is updated during the read() call (i.e. at the beginning of a tick). Internally, we might have to split up the calls to CSoundFile::ReadNote() and the rest of CSoundFile::Read(). Further complications arise from interactive functions that e.g. set the current play position or tempo. The semantics of doing such things before calling advance_tick() and after calling it need to be considered.

One challenge here is going to be that, from what I understand, information like get_current_tick_frames() needs to be available before the actual read() call, but currently this information is updated during the read() call

This is precisely the reason why I think we need the explicit advance_tick() call or something similar. Unless advance_tick() got called, the information would apply to the previous, just finished, tick (what happens on seek and song start needs to be considered here). And yes, that obviously requires splitting CSoundFile::Read() into multiple functions. However, I do not think that can be avoided anyway, regardless of what the API looks like. It currently does too many things at once, which makes designing an API on top of the current implementation close to infeasible, or at the very least inflexible and limited in what use cases it could solve. Preferably, the CSoundFile::Read() split would both, closely match the exported libopenmpt API, as well as suite the internal needs of the OpenMPT playback engine.

https://forum.openmpt.org/index.php?topic=6367.0

https://forum.openmpt.org/index.php?topic=6656

Note that the recently-added CSoundFile::ReadOneTick demonstrates how this can be implemented:

1. Call CSoundFile::ReadNote, which parses the next tick and returns the length of that tick.
2. After that, CSoundFile::Read can be called with that length.

https://forum.openmpt.org/index.php?topic=6919

Hi. I'm not very familiar with the standard way of doing these things, but might it make sense to have this setup?

"stopReadAtOrderEnd" and "priorReadHitOrderEnd" flags

If user sets the stopReadAtOrderEnd flag, each call to read() will fill the buffer as normal, unless it hits the end of an order, at which point it will fill the buffer only up to the end of that order. When this happens, read() will also set the "priorReadHitOrderEnd" flag (which is otherwise cleared). Subsequent calls to read() continue filling the buffer as normal until the next order-end event.

To react to a change in order, the user could set the "stopReadAtOrderEnd" flag, then check the "priorReadHitOrderEnd" flag after each read(). When the "priorReadHitOrderEnd" flag becomes set, the user could react by running their order-change logic, then immediately call read() again to fill the rest of the buffer.

The same could be done for rows with "stopReadAtRowEnd" and "priorReadHitRowEnd" or even ticks with "stopReadAtTickEnd" and "priorReadHitTickEnd".

(Sorry for the mass revisions. I didn't realize they'd all show up in the history.)

The same could be done for rows with "stopReadAtRowEnd" and "priorReadHitRowEnd" or even ticks with "stopReadAtTickEnd" and "priorReadHitTickEnd".

All of these are representable in a more general way by allowing to query the tick length and always reading the exact tick length amount. There are no additional flags or state required.

I see. So can you get a tick length (in samples) when you starting playing the mod file, and then just keep using that same tick length throughout the play?

No, you would query the tick length before/inbetween/after each tick. This is a detail that has yet to be determined.

The tick length changes based on speed/tempo/shuffle.

Ok. So, the user follows up each read with a query of how many ticks that read contained, keep a tally of the ticks read, use that to determine when they are approaching the point in the mod that they care about, then shift to reading tick-by-tick until they have hit their mark. Is that the idea?

EDIT: Or, you say "This is a detail that has yet to be determined.", so is this one of a few possible ideas?

Yes, that's the idea. Note that this is in no way different in principle from what you are suggesting, with the only difference that the position checks happen outside of libopenmpt instead of inside. This has the major advantage of covering any and all kinds of events any user might care about, as opposed to adding functions and state the libopenmpt for each and every one of them.

The aspect that has yet to be determined, is how to handle tick transition. I suspect there may be legitimate reasons to inspect playback state right after a tick has been completely rendered, as well as right after a tick has been parsed and not yet rendered at all, or even in an in-between state (whatever that implies).

examples:

• jumping to another pattern has to be done before a new tick has been started/parsed
• querying the current/future tempo/speed makes more sense after the next tick has already been parsed

I see one technical difference:
Libopenmpt is already tracking ticks, rows and orders as a natural part of its process, so there is a negligible performance penalty for exposing this information to the user. On the other hand, the act of reading tick-by-tick does incur a notable performance penalty.

To examine this performance penalty, I picked a simple song that has stable ticks, rows and orders and worked out the samples per tick:

• 146875 samples per order - calculated using the callback I wrote earlier as an average from 38 order renderings and with a standard deviation of 514 (a reasonably consistent result). The callback is performant: one function pointer call at the end of each row.
• 32 rows per order
• 5 ticks per row
• 918 samples per tick (rounded up)

I altered a test program from filling up the audio buffer in one mod::read() call, to filling it up in multiple mod::read() calls that were maxed at 918 samples per read. This represents the equivalent of reading tick-by-tick for this particular song.

When I ran the song with the test program, it came out heavily distorted. Admittedly, the distortion went away after I bumped the max samples to (int)(918*1.2) = 1101 samples per read. However, my computer has a 4GHz quad-core processor, running at 17% cpu outside of the test program. The song has 9 channels and the test program is a console application dedicated exclusively to playing the mod (I removed the callback and all console output). I expect that this test is easier for libopenmpt than the average use case.

I recognize that there may be better ways for a user to count ticks than what I am testing for. I'm also open to any critiques on this test.

EDIT: I just tried the test again, with the same song, but with a single solo'd channel. I tried soloing each channel in turn. It didn't have an appreciable effect.

And, yeah, I recognize that my test invalidates my earlier idea of flags... at least as far as ticks are concerned.

It occurred to me that reading tick-by-tick might work better if it was only for a short while. I modified the program to fill the buffer normally unless I hit a particular key, then it would read tick-by-tick for 2 ticks before returning to filling the buffer again. I chose to use two ticks because I realized that my audio buffer was at 1024, which is less than 918*2.

The result was more palatable. However, there was a quick "crunch" like a footstep in snow. Sometimes it was too quiet to hear, sometimes loud and distinct.

Your measurements do not make much sense to me. libopenmpt already renders at max one single tick at a time. You cannot render any module any other way anyway. The only thing that would differ is returning to the caller instead of continuing inside libopenmpt.

If the output was distorted for you, you probably did something wrong, or coupled the rendered amount to the sound output buffer length or to the screen update interval (which is a fair thing to do if you control the granularity, but makes no sense if the granularity is adopted to the module tick structure).

It's possible. I was thinking that the read function call had some static time overhead that was being compounded with more frequent calls, though I haven't actually read the function to see if this is true. I'll double check my code.

You were right. I had a bug while advancing the audio stream pointer as I was filling the stream piece by piece from libopenmpt. After I fixed that, things worked fine all the way down to adding 6 samples per read. It started glitching at 5 samples per read, but that is far lower than what is needed. Anyway, I am sorry for wasting your time with all that.

It occurs to me that your design suggestion of using the "tick_auto_advance" flag actually seems somewhat similar to my earlier suggestion. The second flag in my suggestion wouldn't make sense for ticks anyway, since they are smaller than any reasonable read() and the second flag was to let you wait for the next read that contained the event.

However, I'm confused about what you mean when you say that tick_auto_advance==false makes the system require "manual tock advancing". How does manual tock advancing occur? Does the read() only accept sample size of 1, or is the read disabled altogether and advance_tick() is the way advance?

You describe your dilemma as "regardless of what the API looks like. It currently does too many things at once". It sounds like you're describing the solution as breaking up the steps of methods like read(). This ise a useful way to give more control to those that need it, but would it make sense to also leave the monolithic methods for those who don't need that granularity, or would be daunted by its complexity? The monolithic methods could just be a series of calls to other functions that the user would have access to directly if they wanted. In fact, the monolithic methods could provide a form of documentation for how to effectively manage advanced control.

Also, it seems like "advance_tick()" should end at the earliest possible point of interest, then have new methods to advance to subsequent points of interest, like "render_tick()" and "parse_tick()". What should happen if "advance_tick()" is called after calls to subsequent stage methods like "render_tick()" have occurred? It could recognize which stage the process is in, complete the uncompleted stages, then advance to the end of the current tick (and, thus, the start of the next). Alternately, it could error out.

But just having "advance_tick()" pause at the earliest possible point is a good start and provides the space to add more interaction points down the road.