summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorTuomas Virtanen <katajakasa@gmail.com>2018-06-27 23:17:47 +0300
committerTuomas Virtanen <katajakasa@gmail.com>2018-06-27 23:17:47 +0300
commitf0d0aa50910ba9536f40e8a635bb4f70de84a76f (patch)
tree3f58c51353a165d79d4d0ee9b5f2c6f64e87678a
parentc7fc4f2ca9a0d750f32a9f6cf7c86cd2ac548d0f (diff)
Add documentation and api cleanups
-rw-r--r--.gitignore1
-rw-r--r--Doxyfile4
-rw-r--r--include/kitchensink/kitchensink.h8
-rw-r--r--include/kitchensink/kitcodec.h13
-rw-r--r--include/kitchensink/kitconfig.h8
-rw-r--r--include/kitchensink/kiterror.h24
-rw-r--r--include/kitchensink/kitformat.h15
-rw-r--r--include/kitchensink/kitlib.h105
-rw-r--r--include/kitchensink/kitplayer.h2
-rw-r--r--include/kitchensink/kitsource.h160
-rw-r--r--src/internal/audio/kitaudio.c6
-rw-r--r--src/kitlib.c3
12 files changed, 319 insertions, 30 deletions
diff --git a/.gitignore b/.gitignore
index b59a006..100120e 100644
--- a/.gitignore
+++ b/.gitignore
@@ -36,3 +36,4 @@
# Other
build/
+docs/ \ No newline at end of file
diff --git a/Doxyfile b/Doxyfile
index ad99dae..db85229 100644
--- a/Doxyfile
+++ b/Doxyfile
@@ -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;
}
}