diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 133 |
1 files changed, 133 insertions, 0 deletions
@@ -62,6 +62,139 @@ To install these packages in ArchLinux: pacman -S imagemagick libsndfile ``` +## Conversion tool usage + +The conversion tool takes four parameters: the desired mode, input image filename, output WAV filename and sampling rate. The last parameter can be omitted and defaults to `48000`Hz. + +Example usage: +``` +./sstv-encode pd90 ../test/test-image.bmp test.wav 44800 +``` + +The above call produces `test.wav` in the current directory. + +## Library usage + +### Return codes + +Each library function returns an error code that it's advisable you check. A simple check for `SSTV_OK` is enough, unless you want to handle particular errors differently. + +### Initialization + +Library initialization is done with a call to `sstv_init(alloc_func, dealloc_func)`, where the two parameters are function pointers to the allocation and deallocation functions you want `libsstv` to use internally (e.g. `malloc` and `free`). + +If the library is not initialized it can still be used, but only a precompiled maximum number of encoders (`DEFAULT_ENCODER_CONTEXT_COUNT`, default value `4`) can be used simultaneously. This number can be adjusted by passing it to `cmake` at compile time: + +``` +cmake . -DDEFAULT_ENCODER_CONTEXT_COUNT=8 +``` + +If you only encode one image at a time it is safe to skip initialization. + +Moreover, if you do not call `sstv_init()` you will not be able to use further APIs that would require memory allocation to be performed within (see the section on _Images_). + +### Images + +Before encoding and decoding, an image object must be created. The image buffer can either be allocated or it can be provided. + +The quickest way is to create a valid image and allocate its buffer is to call `sstv_create_image_from_mode()`. This function requires that a call to `sstv_init()` has been made (see _Initializetion_ above). + +``` +sstv_image_t image; +if (sstv_create_image_from_mode(&image, SSTV_MODE_FAX480) != SSTV_OK) { + ... error handling ... +} +... write to the image buffer ... +``` + +Otherwise, the user would start by retrieving the image properties of a specific mode: + +``` +uint32_t width, height; +sstv_image_format_t format; +if (sstv_get_mode_image_props(SSTV_MODE_FAX480, &width, &height, &format) != SSTV_OK) { + ... error handling ... +} +``` + +and either rely on `sstv_create_image_from_props()` (which _also_ relies on `sstv_init()`) to allocate an image buffer: + +``` +sstv_image_t image; +if (sstv_create_image_from_props(&image, width, height, format) != SSTV_OK) { + ... error handling ... +} +... write to the image buffer ... +``` + +or use an existing buffer to initialize an image structure with `sstv_pack_image()`: + +``` +uint8_t *buffer = ...; + +sstv_image_t image; +if (sstv_pack_image(&image, width, height, format, buffer) != SSTV_OK) { + ... error handling ... +} +``` + +Only images initialized with `sstv_create_image_from_mode()` and `sstv_create_image_from_props()` must be destroyed with `sstv_delete_image()`. + +Pixel format conversions can be performed in-place on an image by calling `sstv_convert_image()`, with the limitation that the target format must fit within the original memory (e.g. grayscale to RGB conversions will fail with `SSTV_UNSUPPORTED_CONVERSION`). + +### Signal management + +Signals (`sstv_signal_t`) are objects that hold a chunk of the raw audio. They can only be created on a preallocated buffer: + +``` +uint8_t signal_buffer[SIGNAL_BUFFER_CAPACITY]; +sstv_signal_t signal; +if (sstv_pack_signal(&signal, SSTV_SAMPLE_INT16, SIGNAL_BUFFER_CAPACITY, signal_buffer) != SSTV_OK) { + ... error handling ... +} +``` + +### Encoding + +#### Encoder management + +You can use `sstv_create_encoder()` and `sstv_delete_encoder()` to request and return an encoder context to the library. + +``` +sstv_image_t image; +... set up image ... + +const size_t SAMPLE_RATE = 48000 + +void *ctx; +if (sstv_create_encoder(&ctx, image, SSTV_MODE_FAX480, SAMPLE_RATE) != SSTV_OK) { + ... error handling ... +} +``` + +#### Encoding + +The actual encoding is performed with multiple calls to `sstv_encode()`, until the whole output has been produced: + +``` +void *ctx; +... encoder context creation ... + +sstv_signal_t signal; +... signal packing ... + +sstv_error_t rc = SSTV_OK; +while (rc != SSTV_ENCODE_END) { + if (sstv_encode(ctx, &signal) != SSTV_ENCODE_SUCCESSFUL) { + ... error handling ... + } +} +``` + +Note that `sstv_encode()` does not return `SSTV_OK` on success but `SSTV_ENCODE_SUCCESSFUL`. + +The library does not allocate further memory than that allocated for the images or that provided by the user via images or signals. + ## License Copyright (c) 2018-2023 Vasile Vilvoiu (YO7JBP) <vasi@vilvoiu.ro> |