Author Topic: [SOLVED][API] what is openmpt_stream_get_file_callbacks() ?  (Read 1165 times)

Offline jseb

  • Shy artist
  • Posts: 4
[SOLVED][API] what is openmpt_stream_get_file_callbacks() ?
« on: September 06, 2018, 15:26:31 »
Hello,

I'm learning to use the API , and when reading this:

Code: [Select]
mod = openmpt_module_create2( openmpt_stream_get_file_callbacks(), file, &libopenmpt_example_logfunc, NULL, &libopenmpt_example_errfunc, NULL, &mod_err, &mod_err_str, NULL );

I wonder what the first argument openmpt_stream_get_file_callbacks() is doing.

Reading the doc for openmpt_module_create2, i thought at first sight it was a callback function which will be invoked every time we need to fill a buffer.
But it doesn't seem to be the case: if it was the case, it should give frequency of refill, and it should be an user defined callback.

Moreover, the buffer filling is done by this function in the rendering loop:
Code: [Select]
count = openmpt_module_read_interleaved_stereo( mod, SAMPLERATE, BUFFERSIZE, buffer );



The help for openmpt_stream_get_file_callbacks() doesn't say much…

Code: [Select]
◆ openmpt_stream_get_file_callbacks()
static openmpt_stream_callbacks openmpt_stream_get_file_callbacks (void)

Thank you.
« Last Edit: September 06, 2018, 16:24:52 by jseb »

Offline manx

  • OpenMPT Developers
  • *****
  • Posts: 198
Re: [API] what is openmpt_stream_get_file_callbacks() ?
« Reply #1 on: September 06, 2018, 15:39:20 »
Code: [Select]
mod = openmpt_module_create2( openmpt_stream_get_file_callbacks(), file, &libopenmpt_example_logfunc, NULL, &libopenmpt_example_errfunc, NULL, &mod_err, &mod_err_str, NULL );

I wonder what the first argument openmpt_stream_get_file_callbacks() is doing.

Reading the doc for openmpt_module_create2, i thought at first sight it was a callback function which will be invoked every time we need to fill a buffer.
But it doesn't seem to be the case: if it was the case, it should give frequency of refill, and it should be an user defined callback.

The help for openmpt_stream_get_file_callbacks() doesn't say much…

The first argument to openmpt_module_create2() is a structure containing function pointers to file i/o functions, in particular, a read, and optionally seek and tell functions. Only read is required, but file i/o will require less resources when also seek and tell are provided. These callbacks operate on the file stream which is passed as the second argument to openmpt_module_create2(). This stream pointer is in turn passed to the callback functions provided in the struct. See https://lib.openmpt.org/doc/group__libopenmpt__c.html#gaeccd341852695cc71d8a5e3ac47ff168.

openmpt_stream_get_file_callbacks() fills the callbacks structure as required for a C stdio FILE* object, which is passed as the second argument as file in the quoted example.
I.e. if you open your file via fopen(), you can just use openmpt_stream_get_file_callbacks().
If you open your file using standard unix file descriptor, you can use openmpt_stream_get_fd_callbacks().
If you use other means for file i/o, you need to provide suitable callback functions yourself.

I'll add some more documentation to openmpt_stream_get_file_callbacks() and openmpt_stream_get_fd_callbacks().

Moreover, the buffer filling is done by this function in the rendering loop:
Code: [Select]
count = openmpt_module_read_interleaved_stereo( mod, SAMPLERATE, BUFFERSIZE, buffer );

This fills the output buffer as required by the API user. This has nothing to do with file i/o. File loadingg is finished as soon as openmpt_module_create2() returns.

Offline jseb

  • Shy artist
  • Posts: 4
Re: [SOLVED][API] what is openmpt_stream_get_file_callbacks() ?
« Reply #2 on: September 06, 2018, 16:32:47 »
Thank you, i understand now.