diff options
author | Tuomas Virtanen <katajakasa@gmail.com> | 2018-06-27 23:17:47 +0300 |
---|---|---|
committer | Tuomas Virtanen <katajakasa@gmail.com> | 2018-06-27 23:17:47 +0300 |
commit | f0d0aa50910ba9536f40e8a635bb4f70de84a76f (patch) | |
tree | 3f58c51353a165d79d4d0ee9b5f2c6f64e87678a | |
parent | c7fc4f2ca9a0d750f32a9f6cf7c86cd2ac548d0f (diff) |
Add documentation and api cleanups
-rw-r--r-- | .gitignore | 1 | ||||
-rw-r--r-- | Doxyfile | 4 | ||||
-rw-r--r-- | include/kitchensink/kitchensink.h | 8 | ||||
-rw-r--r-- | include/kitchensink/kitcodec.h | 13 | ||||
-rw-r--r-- | include/kitchensink/kitconfig.h | 8 | ||||
-rw-r--r-- | include/kitchensink/kiterror.h | 24 | ||||
-rw-r--r-- | include/kitchensink/kitformat.h | 15 | ||||
-rw-r--r-- | include/kitchensink/kitlib.h | 105 | ||||
-rw-r--r-- | include/kitchensink/kitplayer.h | 2 | ||||
-rw-r--r-- | include/kitchensink/kitsource.h | 160 | ||||
-rw-r--r-- | src/internal/audio/kitaudio.c | 6 | ||||
-rw-r--r-- | src/kitlib.c | 3 |
12 files changed, 319 insertions, 30 deletions
@@ -36,3 +36,4 @@ # Other build/ +docs/
\ No newline at end of file @@ -1117,7 +1117,7 @@ HTML_FOOTER = # obsolete. # This tag requires that the tag GENERATE_HTML is set to YES. -HTML_STYLESHEET = +HTML_STYLESHEET = # The HTML_EXTRA_STYLESHEET tag can be used to specify additional user-defined # cascading style sheets that are included after the standard style sheets @@ -1130,7 +1130,7 @@ HTML_STYLESHEET = # list). For an example see the documentation. # This tag requires that the tag GENERATE_HTML is set to YES. -HTML_EXTRA_STYLESHEET = +HTML_EXTRA_STYLESHEET = doxygen-custom.css # The HTML_EXTRA_FILES tag can be used to specify one or more extra images or # other source files which should be copied to the HTML output directory. Note diff --git a/include/kitchensink/kitchensink.h b/include/kitchensink/kitchensink.h index 568c0d8..7fc08e6 100644 --- a/include/kitchensink/kitchensink.h +++ b/include/kitchensink/kitchensink.h @@ -1,6 +1,14 @@ #ifndef KITCHENSINK_H #define KITCHENSINK_H +/** + * @brief Header aggregator + * + * @file kitchensink.h + * @author Tuomas Virtanen + * @date 2018-06-27 + */ + #include "kitchensink/kitlib.h" #include "kitchensink/kiterror.h" #include "kitchensink/kitformat.h" diff --git a/include/kitchensink/kitcodec.h b/include/kitchensink/kitcodec.h index 76b53a4..589f84d 100644 --- a/include/kitchensink/kitcodec.h +++ b/include/kitchensink/kitcodec.h @@ -1,6 +1,14 @@ #ifndef KITCODEC_H
#define KITCODEC_H
+/**
+ * @brief Codec type
+ *
+ * @file kitcodec.h
+ * @author Tuomas Virtanen
+ * @date 2018-06-25
+ */
+
#ifdef __cplusplus
extern "C" {
#endif
@@ -8,8 +16,11 @@ extern "C" { #define KIT_CODEC_NAME_MAX 8
#define KIT_CODEC_DESC_MAX 48
+/**
+ * @brief Contains information about the used codec for playback
+ */
typedef struct Kit_Codec {
- unsigned int threads; ///< Currently enabled threads
+ unsigned int threads; ///< Currently enabled threads (For all decoders)
char name[KIT_CODEC_NAME_MAX]; ///< Codec short name, eg. "ogg" or "webm"
char description[KIT_CODEC_DESC_MAX]; ///< Codec longer, more descriptive name
} Kit_Codec;
diff --git a/include/kitchensink/kitconfig.h b/include/kitchensink/kitconfig.h index e8b2d01..8eda779 100644 --- a/include/kitchensink/kitconfig.h +++ b/include/kitchensink/kitconfig.h @@ -1,6 +1,14 @@ #ifndef KITCONFIG_H #define KITCONFIG_H +/** + * @brief Public API configurations + * + * @file kitconfig.h + * @author Tuomas Virtanen + * @date 2018-06-25 + */ + #if defined _WIN32 || defined __CYGWIN__ #define KIT_DLL_IMPORT __declspec(dllimport) #define KIT_DLL_EXPORT __declspec(dllexport) diff --git a/include/kitchensink/kiterror.h b/include/kitchensink/kiterror.h index 824ea8c..e6c2acd 100644 --- a/include/kitchensink/kiterror.h +++ b/include/kitchensink/kiterror.h @@ -1,14 +1,38 @@ #ifndef KITERROR_H #define KITERROR_H +/** + * @brief Error handling functions + * + * @file kiterror.h + * @author Tuomas Virtanen + * @date 2018-06-25 + */ + #include "kitchensink/kitconfig.h" #ifdef __cplusplus extern "C" { #endif +/** + * @brief Returns the latest error. This is set by SDL_kitchensink library functions on error. + * + * @return Error message or NULL + */ KIT_API const char* Kit_GetError(); + +/** + * @brief Sets the error message. This should really only be used by the library. + * + * @param fmt Message format + * @param ... Message arguments + */ KIT_API void Kit_SetError(const char* fmt, ...); + +/** + * @brief Clears latest error message. After this, Kit_GetError() will return NULL. + */ KIT_API void Kit_ClearError(); #ifdef __cplusplus diff --git a/include/kitchensink/kitformat.h b/include/kitchensink/kitformat.h index 4c428c5..3e8df91 100644 --- a/include/kitchensink/kitformat.h +++ b/include/kitchensink/kitformat.h @@ -1,15 +1,24 @@ #ifndef KITFORMAT_H
#define KITFORMAT_H
-#include <stdbool.h>
+/**
+ * @brief Audio/video output format type
+ *
+ * @file kitformat.h
+ * @author Tuomas Virtanen
+ * @date 2018-06-25
+ */
#ifdef __cplusplus
extern "C" {
#endif
+/**
+ * @brief Contains information about the data format coming out from the player
+ */
typedef struct Kit_OutputFormat {
- unsigned int format; ///< SDL Format
- bool is_signed; ///< Signedness (if audio)
+ unsigned int format; ///< SDL Format (SDL_PixelFormat if video/subtitle, SDL_AudioFormat if audio)
+ int is_signed; ///< Signedness, 1 = signed, 0 = unsigned (if audio)
int bytes; ///< Bytes per sample per channel (if audio)
int samplerate; ///< Sampling rate (if audio)
int channels; ///< Channels (if audio)
diff --git a/include/kitchensink/kitlib.h b/include/kitchensink/kitlib.h index 85ce2d4..a5fe913 100644 --- a/include/kitchensink/kitlib.h +++ b/include/kitchensink/kitlib.h @@ -1,43 +1,118 @@ #ifndef KITLIB_H #define KITLIB_H +/** + * @brief Library initialization and deinitialization functionality + * + * @file kitlib.h + * @author Tuomas Virtanen + * @date 2018-06-25 + */ + #include "kitchensink/kitconfig.h" #ifdef __cplusplus extern "C" { #endif -enum { // These should match libass - KIT_FONT_HINTING_NONE = 0, - KIT_FONT_HINTING_LIGHT, - KIT_FONT_HINTING_NORMAL, - KIT_FONT_HINTING_NATIVE, +/** + * @brief Font hinting options. Used as values for Kit_SetHint(KIT_HINT_FONT_HINTING, ...). + */ +enum { + KIT_FONT_HINTING_NONE = 0, ///< No hinting. This is recommended option + KIT_FONT_HINTING_LIGHT, ///< Light hinting. Use this if you need hinting + KIT_FONT_HINTING_NORMAL, ///< Not recommended, please see libass docs for details + KIT_FONT_HINTING_NATIVE, ///< Not recommended, please see libass docs for details KIT_FONT_HINTING_COUNT }; +/** + * @brief SDL_kitchensink library version container + */ typedef struct Kit_Version { - unsigned char major; - unsigned char minor; - unsigned char patch; + unsigned char major; ///< Major version number, raising this signifies API breakage + unsigned char minor; ///< Minor version number, small/internal changes + unsigned char patch; ///< Patch version number, bugfixes etc. } Kit_Version; +/** + * @brief Library hint types. Used as keys for Kit_SetHint(). + * + * Note that all of these must be set *before* player initialization for them to take effect! + */ typedef enum Kit_HintType { - KIT_HINT_FONT_HINTING, - KIT_HINT_THREAD_COUNT, - KIT_HINT_VIDEO_BUFFER_FRAMES, - KIT_HINT_AUDIO_BUFFER_FRAMES, - KIT_HINT_SUBTITLE_BUFFER_FRAMES + KIT_HINT_FONT_HINTING, ///< Set font hinting mode (currently used for libass) + KIT_HINT_THREAD_COUNT, ///< Set thread count for ffmpeg (1 by default) + KIT_HINT_VIDEO_BUFFER_FRAMES, ///< Video output buffer frames (3 by default) + KIT_HINT_AUDIO_BUFFER_FRAMES, ///< Audio output buffers (64 by default) + KIT_HINT_SUBTITLE_BUFFER_FRAMES ///< Subtitle output buffers (64 by default, used by image subtitles) } Kit_HintType; +/** + * @brief Library initialization options, please see Kit_Init() + * + */ enum { - KIT_INIT_NETWORK = 0x1, - KIT_INIT_ASS = 0x2 + KIT_INIT_NETWORK = 0x1, ///< Initialise ffmpeg network support + KIT_INIT_ASS = 0x2 ///< Initialize libass support (library must be linked statically or loadable dynamically) }; +/** + * @brief Initialize SDL_kitchensink library. + * + * This MUST be run before doing anything. After you are done using the library, you should use Kit_Quit() to + * deinitialize everything. Otherwise there might be resource leaks. + * + * Following flags can be used to initialize subsystems: + * - `KIT_INIT_NETWORK` for ffmpeg network support (playback from the internet, for example) + * - `KIT_INIT_ASS` for libass subtitles (text and ass/ssa subtitle support) + * + * Note that if this function fails, the failure reason should be available via Kit_GetError(). + * + * For example: + * ``` + * if(Kit_Init(KIT_INIT_NETWORK|KIT_INIT_ASS) != 0) { + * fprintf(stderr, "Error: %s\n", Kit_GetError()); + * return 1; + * } + * ``` + * + * @param flags Library initialization flags + * @return Returns 0 on success, 1 on failure. + */ KIT_API int Kit_Init(unsigned int flags); + +/** + * @brief Deinitializes SDL_kitchensink + * + * Note that any calls to library functions after this will cause undefined behaviour! + */ KIT_API void Kit_Quit(); + +/** + * @brief Sets a librarywide hint + * + * This can be used to set hints on how the library should behave. See Kit_HintType + * for all the options. + * + * @param type Hint type (refer to Kit_HintType for options) + * @param value Value for the hint + */ KIT_API void Kit_SetHint(Kit_HintType type, int value); + +/** + * @brief Gets a previously set or default hint value + * + * @param type Hint type (refer to Kit_HintType for options) + * @return Hint value + */ KIT_API int Kit_GetHint(Kit_HintType type); + +/** + * @brief Can be used to fetch the version of the linked SDL_kitchensink library + * + * @param version Allocated Kit_Version + */ KIT_API void Kit_GetVersion(Kit_Version *version); #ifdef __cplusplus diff --git a/include/kitchensink/kitplayer.h b/include/kitchensink/kitplayer.h index 27e268d..572e373 100644 --- a/include/kitchensink/kitplayer.h +++ b/include/kitchensink/kitplayer.h @@ -11,8 +11,6 @@ #include <SDL2/SDL_surface.h> #include <SDL2/SDL_mutex.h> -#include <stdbool.h> - #ifdef __cplusplus extern "C" { #endif diff --git a/include/kitchensink/kitsource.h b/include/kitchensink/kitsource.h index db6ee21..a9da78e 100644 --- a/include/kitchensink/kitsource.h +++ b/include/kitchensink/kitsource.h @@ -1,6 +1,14 @@ #ifndef KITSOURCE_H #define KITSOURCE_H +/** + * @brief Video/Audio source file handling + * + * @file kitsource.h + * @author Tuomas Virtanen + * @date 2018-06-27 + */ + #include <inttypes.h> #include "kitchensink/kitconfig.h" @@ -8,6 +16,11 @@ extern "C" { #endif +/** + * @brief Type of the stream. + * + * This is used by Kit_SourceStreamInfo and Kit_GetSourceStreamInfo(). + */ typedef enum Kit_StreamType { KIT_STREAMTYPE_UNKNOWN, ///< Unknown stream type KIT_STREAMTYPE_VIDEO, ///< Video stream @@ -17,25 +30,166 @@ typedef enum Kit_StreamType { KIT_STREAMTYPE_ATTACHMENT ///< Attachment stream (images, etc) } Kit_StreamType; +/** + * @brief Audio/video source. + * + * Should be created using Kit_CreateSourceFromUrl() or Kit_CreateSourceFromCustom(), and + * closed with Kit_CloseSource(). + * + * Source must exist for the whole duration of using a player. You must take care of closing the source + * yourself after you are done with it! + */ typedef struct Kit_Source { void *format_ctx; ///< FFmpeg: Videostream format context void *avio_ctx; ///< FFmpeg: AVIO context } Kit_Source; +/** + * @brief Information for a source stream. + * + * Fetch information by using Kit_GetSourceStreamInfo(). + */ typedef struct Kit_SourceStreamInfo { int index; ///< Stream index Kit_StreamType type; ///< Stream type } Kit_SourceStreamInfo; -typedef int (*Kit_ReadCallback)(void*, uint8_t*, int); -typedef int64_t (*Kit_SeekCallback)(void*, int64_t, int); +/** + * @brief Callback function type for reading data stream + * + * Used by Kit_CreateSourceFromCustom() for reading data from user defined source. + * + * A custom reader function must accept three arguments: + * - userdata, this is the same data as set as last argument for Kit_CreateSourceFromCustom + * - buf, a buffer the data must be copied into + * - size, how much data you are expected to provide at maximum. + * + * The function must return the amount of bytes copied to the buffer. + * + * Note that this callback is passed directly to ffmpeg avio, so please refer to ffmpeg documentation + * for any further details. + */ +typedef int (*Kit_ReadCallback)(void *userdata, uint8_t *buf, int size); + +/** + * @brief Callback function type for seeking data strema + * + * Used by Kit_CreateSourceFromCustom() for seeking a user defined source. + * + * A custom seeking function must accept three arguments: + * - userdata, this is the same data as set as last argument for Kit_CreateSourceFromCustom + * - offset, an seeking offset in bytes + * - whence, reference position for the offset. + * + * The function must return the position (in bytes) we seeked to. + * + * Note that this callback is passed directly to ffmpeg avio, so please refer to ffmpeg documentation + * for any further details. + */ +typedef int64_t (*Kit_SeekCallback)(void *userdata, int64_t offset, int whence); + +/** + * @brief Create a new source from a given url + * + * This can be used to load video/audio from a file or network resource. If you wish to + * use network resources, make sure the library has been initialized using KIT_INIT_NETWORK flag. + * + * This function will return an initialized Kit_Source on success. Note that you need to manually + * free the source when it's no longer needed by calling Kit_CloseSource(). + * + * On failure, this function will return NULL, and further error data is available via Kit_GetError(). + * + * For example: + * ``` + * if(Kit_CreateSourceFromUrl(filename) == NULL) { + * fprintf(stderr, "Error: %s\n", Kit_GetError()); + * return 1; + * } + * ``` + * + * @param url File path or URL to a video/audio resource + * @return Returns an initialized Kit_Source* on success or NULL on failure + */ +KIT_API Kit_Source* Kit_CreateSourceFromUrl(const char *url); -KIT_API Kit_Source* Kit_CreateSourceFromUrl(const char *path); +/** + * @brief Create a new source from custom data + * + * This can be used to load data from any resource via the given read and seek functions. + * + * This function will return an initialized Kit_Source on success. Note that you need to manually + * free the source when it's no longer needed by calling Kit_CloseSource(). + * + * On failure, this function will return NULL, and further error data is available via Kit_GetError(). + * + * For example: + * ``` + * if(Kit_CreateSourceFromUrl(filename) == NULL) { + * fprintf(stderr, "Error: %s\n", Kit_GetError()); + * return 1; + * } + * ``` + * + * @param read_cb Read function callback + * @param seek_cb Seek function callback + * @param userdata Any data (or NULL). Will be passed to read_cb and/or seek_cb functions as-is. + * @return Returns an initialized Kit_Source* on success or NULL on failure + */ KIT_API Kit_Source* Kit_CreateSourceFromCustom(Kit_ReadCallback read_cb, Kit_SeekCallback seek_cb, void *userdata); + +/** + * @brief Closes a previously initialized source + * + * Closes a Kit_Source that was previously created by Kit_CreateSourceFromUrl() or Kit_CreateSourceFromCustom() + * and frees up all memory and resources used by it. Using the source for anything after this will + * lead to undefined behaviour. + * + * Passing NULL as argument is valid, and will do nothing. + * + * @param src Previously initialized Kit_Source to close + */ KIT_API void Kit_CloseSource(Kit_Source *src); +/** + * @brief Fetches stream information for a given stream index + * + * Sets fields for given Kit_SourceStreamInfo with information about the stream. + * + * For example: + * ``` + * Kit_SourceStreamInfo stream; + * if(Kit_GetSourceStreamInfo(source, &stream, 0) == 1) { + * fprintf(stderr, "Error: %s\n", Kit_GetError()); + * return 1; + * } + * fprintf(stderr, "Stream type: %s\n", Kit_GetKitStreamTypeString(stream.type)) + * ``` + * + * @param src Source to query from + * @param info A previously allocated Kit_SourceStreamInfo to fill out + * @param index Stream index (starting from 0) + * @return 0 on success, 1 on error. + */ KIT_API int Kit_GetSourceStreamInfo(const Kit_Source *src, Kit_SourceStreamInfo *info, int index); + +/** + * @brief Gets the amount of streams in source + * + * @param src Source to query from + * @return Number of streams in the source + */ KIT_API int Kit_GetSourceStreamCount(const Kit_Source *src); + +/** + * @brief Gets the best stream index for a given stream type. + * + * Find the best stream index for a given stream type, if one exists. If there is no + * stream for the wanted type, will return -1. + * + * @param src Source to query from + * @param type Stream type + * @return Index number on success (>=0), -1 on error. + */ KIT_API int Kit_GetBestSourceStream(const Kit_Source *src, const Kit_StreamType type); #ifdef __cplusplus diff --git a/src/internal/audio/kitaudio.c b/src/internal/audio/kitaudio.c index ec4fc13..8cf2d3e 100644 --- a/src/internal/audio/kitaudio.c +++ b/src/internal/audio/kitaudio.c @@ -88,13 +88,13 @@ int _FindSDLSampleFormat(enum AVSampleFormat fmt) { }
}
-bool _FindSignedness(enum AVSampleFormat fmt) {
+int _FindSignedness(enum AVSampleFormat fmt) {
switch(fmt) {
case AV_SAMPLE_FMT_U8P:
case AV_SAMPLE_FMT_U8:
- return false;
+ return 0;
default:
- return true;
+ return 1;
}
}
diff --git a/src/kitlib.c b/src/kitlib.c index b141208..9011ea3 100644 --- a/src/kitlib.c +++ b/src/kitlib.c @@ -44,7 +44,7 @@ int Kit_Init(unsigned int flags) { Kit_LibraryState *state = Kit_GetLibraryState(); if(state->init_flags != 0) { - Kit_SetError("Kitchensink is already initialized."); + Kit_SetError("SDL_kitchensink is already initialized"); goto exit_0; } @@ -57,6 +57,7 @@ int Kit_Init(unsigned int flags) { } if(flags & KIT_INIT_ASS) { if(Kit_InitASS(state) != 0) { + Kit_SetError("Failed to initialize libass"); goto exit_1; } } |