Revamp API and start using doxygen

The API used to be designed in such a way to where it would expect
exports for each individual source/output/encoder/etc.  You would export
functions for each and it would automatically load those functions based
on a specific naming scheme from the module.

The idea behind this was that I wanted to limit the usage of structures
in the API so only functions could be used.  It was an interesting idea
in theory, but this idea turned out to be flawed in a number of ways:

 1.) Requiring exports to create sources/outputs/encoders/etc meant that
     you could not create them by any other means, which meant that
     things like faruton's .net plugin would become difficult.

 2.) Export function declarations could not be checked, therefore if you
     created a function with the wrong parameters and parameter types,
     the compiler wouldn't know how to check for that.

 3.) Required overly complex load functions in libobs just to handle it.
     It makes much more sense to just have a load function that you call
     manually.  Complexity is the bane of all good programs.

 4.) It required that you have functions of specific names, which looked
     and felt somewhat unsightly.

So, to fix these issues, I replaced it with a more commonly used API
scheme, seen commonly in places like kernels and typical C libraries
with abstraction.  You simply create a structure that contains the
callback definitions, and you pass it to a function to register that
definition (such as obs_register_source), which you call in the
obs_module_load of the module.

It will also automatically check the structure size and ensure that it
only loads the required values if the structure happened to add new
values in an API change.

The "main" source file for each module must include obs-module.h, and
must use OBS_DECLARE_MODULE() within that source file.

Also, started writing some doxygen documentation in to the main library
headers.  Will add more detailed documentation as I go.
This commit is contained in:
jp9000
2014-02-12 08:04:50 -07:00
parent 524ff94912
commit 8e81d8be56
42 changed files with 1120 additions and 1409 deletions

View File

@@ -26,10 +26,31 @@
#include "callback/signal.h"
#include "callback/proc.h"
/* opaque types */
struct obs_display;
struct obs_source;
struct obs_scene;
struct obs_scene_item;
struct obs_output;
struct obs_encoder;
struct obs_service;
typedef struct obs_display *obs_display_t;
typedef struct obs_source *obs_source_t;
typedef struct obs_scene *obs_scene_t;
typedef struct obs_scene_item *obs_sceneitem_t;
typedef struct obs_output *obs_output_t;
typedef struct obs_encoder *obs_encoder_t;
typedef struct obs_service *obs_service_t;
#include "obs-defs.h"
#include "obs-data.h"
#include "obs-ui.h"
#include "obs-properties.h"
#include "obs-source.h"
#include "obs-encoder.h"
#include "obs-output.h"
#include "obs-service.h"
/*
* Main libobs header used by applications.
@@ -47,10 +68,11 @@ extern "C" {
LIBOBS_API_MINOR_VER)
enum obs_source_type {
SOURCE_INPUT,
SOURCE_FILTER,
SOURCE_TRANSITION,
SOURCE_SCENE
OBS_SOURCE_TYPE_INPUT,
OBS_SOURCE_TYPE_FILTER,
OBS_SOURCE_TYPE_TRANSITION,
OBS_SOURCE_TYPE_SCENE
};
/* used for changing the order of items (for example, filters in a source,
@@ -142,23 +164,6 @@ struct encoder_packet {
enum packet_priority priority;
};
/* opaque types */
struct obs_display;
struct obs_source;
struct obs_scene;
struct obs_scene_item;
struct obs_output;
struct obs_encoder;
struct obs_service;
typedef struct obs_display *obs_display_t;
typedef struct obs_source *obs_source_t;
typedef struct obs_scene *obs_scene_t;
typedef struct obs_scene_item *obs_sceneitem_t;
typedef struct obs_output *obs_output_t;
typedef struct obs_encoder *obs_encoder_t;
typedef struct obs_service *obs_service_t;
/* ------------------------------------------------------------------------- */
/* OBS context */
@@ -433,9 +438,8 @@ EXPORT void obs_source_releaseframe(obs_source_t source,
struct source_frame *frame);
/** Default RGB filter handler for generic effect filters */
EXPORT void obs_source_process_filter(obs_source_t filter,
texrender_t texrender, effect_t effect,
uint32_t width, uint32_t height,
EXPORT void obs_source_process_filter(obs_source_t filter, effect_t effect,
uint32_t width, uint32_t height, enum gs_color_format format,
enum allow_direct_render allow_direct);