libxmp 4.6 API changes?

[AliceLR]

There are a couple of open issues that would benefit from having API changes in libxmp 4.6, whenever we decide to do that.

xmp_set_player options: this function allows (and relies on) being used before load for some settings, which is unusual as most of the settings refuse to work until after load. All of these options would be set prior to loading.

• XMP_PLAYER_DEPACK — toggle using depackers on load when linking system libxmp binaries. Is valid but does nothing if they were disabled at compile time. 0: disabled, 1: enabled (default). Not sure how useful this would be.

• XMP_PLAYER_PROWIZARD — toggle using ProWizard on load when linking system libxmp binaries. Is valid but does nothing if they were disabled at compile time. 0: disabled, 1: enabled (default). Not sure how useful this would be.

• XMP_PLAYER_CHECKSUM — select the hash function used after loading. Would be very useful for fuzzing and for older or embedded systems with slow file IO. (Usage of integer division. #400)

  • XMP_CHECKSUM_NONE: no hash. All bytes of xmp_module_info::md5 are 0. No module quirks detection.
  • XMP_CHECKSUM_MD5: use MD5 digest (default).
  • XMP_CHECKSUM_CRC32C: use CRC-32c. All but the first four bytes of xmp_module_info::md5 are 0. Other module details are used in combination with this for the module quirks detection.

I considered an encoding player option too (#324), but this is really better as its own set of functions. The original raw strings would be stored internally away from the API, and the fields already exposed to the API would continue to be stripped to ASCII (names) or left raw (the module comment) for compatibility and debug output.

#define XMP_ENCODE_NONE       0 /* No conversion, return raw data with a terminator */
#define XMP_ENCODE_ASCII      1 /* Replace non-ASCII characters with '.' */
#define XMP_ENCODE_UTF8       2 /* Convert to UTF-8 based on the most likely original encoding */
#define XMP_ENCODE_UTF8_CP437 3 /* Convert to UTF-8 assuming CP437 encoding */
/* and values for any other source encoding libxmp would need to convert to UTF-8, you get the point... */

/* Write the requested string to a buffer using the requested encoding. At most (dest_size - 1) bytes
 * will be written, plus a null terminator. Returns the final length of the encoded string regardless
 * of the provided buffer size (not including the terminator), or -1 on error.
 * 
 * Provide NULL or <=0 buffer size to get the length without writing anything.
 */
int xmp_get_module_name        (xmp_context *, char *dest, int dest_size, int encoding);
int xmp_get_module_type        (xmp_context *, char *dest, int dest_size, int encoding);
int xmp_get_module_author      (xmp_context *, char *dest, int dest_size, int encoding);
int xmp_get_module_comment     (xmp_context *, char *dest, int dest_size, int encoding);
int xmp_get_sample_name        (xmp_context *, int smp, char *dest, int dest_size, int encoding);
int xmp_get_sample_filename    (xmp_context *, int smp, char *dest, int dest_size, int encoding);
int xmp_get_instrument_name    (xmp_context *, int ins, char *dest, int dest_size, int encoding);
int xmp_get_instrument_filename(xmp_context *, int ins, char *dest, int dest_size, int encoding);

This issue is definitely open to feedback and further API changes...

[sezero]

There is also https://github.com/libxmp/libxmp/blob/master/TODO.5 (the - fix CFLAGS mess item in there can be removed I guess.)