README

* ABOUT

libmodplugw is a wrapper for libmodplug that enables MOD file row and pattern
sample accurate operations. can be used for looping buffers and remixing
a MOD file via 'segments'.

this is not a fork of libmodplug, but a complimentary library.

for libmodplugw to work a MOD file first has to be decoded in memory.
it supports all formats that libmodplug can decode.

public domain license. see LICENSE.

================================================================================
* API

look at ./include/modplugw.h

================================================================================
* EXAMPLE

here is an example of how to extract some patterns from a MOD file and create
OpenAL buffers from the resulted 'segments':

0) allocate the library descriptor:
	modplugw_desc_t *desc = modplugw_alloc_desc(NULL);
	// 'desc' will hold all pattern and row information of the MOD file
	// instead of NULL you can pass a ModPlug_Settings pointer
	// said pointer will be available via 'desc->settings'

1) decode a file buffer:
	modplugw_decode(desc, file_buf, file_buf_sz, 1);
	// you can pass 0 as the last argument to disable verbose mode
	// desc->mod is a (ModPlugFile *)
	// desc->bytes and desc->len hold the entire decoded buffer

2) get some stats:
	// length of the MOD in seconds (float)
	float seconds = modplugw_bytes_to_sec(desc, desc->len);
	// start position of the 2nd pattern in bytes
	unsigned int pos2 = modplugw_get_pattern_offset(desc, 1);
	// how many rows there are in the second pattern
	unsigned int rows2 = modplugw_get_pattern_rows(desc, 1);
	// get length of the second pattern in bytes
	unsigned int len2 = modplugw_get_pattern_len(desc, 1);
	// get where the last pattern ends (end_pattern = last_pattern + 1);
	unsgined int mod_end = modplugw_get_end_pattern_offset(desc);

3) obtain the first and third patterns as segments:
	modplugw_seg_t *seg[2]; // two segment pointers
	seg[0] = modplugw_alloc_pattern_segment(desc, 0, 1); // 1st to 2nd
	seg[1] = modplugw_alloc_pattern_segment(desc, 2, 3); // 3rd to 4th

4) add the second pattern to first segment (first pattern):
	modplugw_seg_t *tmp = modplugw_alloc_pattern_segment(desc, 1, 2); // 2nd to 3rd
	seg[0] = modplugw_append_segments(seg[0], &tmp, 1); // append '1' segment (tmp)
	modplugw_free_segments(tmp, 1); // free 1 (tmp) segment

5) create a segment from a row span and add that to the second segment:
	// start row - 4th pattern, 0eth row
	// end row - 6th pattern, 0eth row
	// this will result in a 2-pattern long segment
	modplugw_seg_t *tmp2 = modplugw_alloc_row_segment(desc, 4, 0, 6, 0);
	seg[1] = modplugw_append_segments(seg[1], &tmp2, 1); // append '1' segment (tmp2)
	modplugw_free_segments(tmp2, 1); // free 1 (tmp2) segment

6) create OpenAL buffers from the two segments and free them:
	ALuint buffers[2];
	alBufferData(buffers[0], format, seg[0]->data, seg[0]->len, frequency);
	alBufferData(buffers[1], format, seg[1]->data, seg[1]->len, frequency);
	modplugw_free_segments(seg, 2);

7) dispose of the descriptor:
	modplugw_free_desc(desc);

================================================================================
* BUILDING

notes:
- 'make' and 'ar' are required for a gcc/mingw build
- if you don't have pkg-config modify INCLUDES and LIBS accordingly
- msvc is not supported by the Makefile, but you can modify it accordingly
- call 'make' in the root path
- call 'make DEBUG=1' to build the libraries with debug symbols
- both a static link library and a dynamic link library will be created in ./lib

it's probably best to static link libmodplugw to your project

================================================================================
* INSTALLING

'make install' is not implemented.

just copy:
- ./lib/* to where libmodplug's libs are
- ./include/* to where libmodplug's includes are

for pkg-config usage find the libmodplug.pc file, make a copy of it named
libmodplugw.pc and modify the file.

================================================================================
* AUTHOR
	lubomir i. ivanov (neolit123 [at] gmail.com)