summaryrefslogtreecommitdiff
path: root/include/kitchensink/kitsource.h
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 /include/kitchensink/kitsource.h
parentc7fc4f2ca9a0d750f32a9f6cf7c86cd2ac548d0f (diff)
Add documentation and api cleanups
Diffstat (limited to 'include/kitchensink/kitsource.h')
-rw-r--r--include/kitchensink/kitsource.h160
1 files changed, 157 insertions, 3 deletions
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