From 5379f0ee5f02ee401b5f445c5c5d44e5ed09fe6f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pablo=20Andr=C3=A9s=20Dorado=20Su=C3=A1rez?= Date: Wed, 25 Oct 2023 15:53:49 -0500 Subject: [PATCH] chore: extend source documentation --- include/find/find_sources.d.ts | 5 +++++ include/find/find_sources.h | 7 +++++++ include/find/source_instance.d.ts | 7 +++++++ include/find/source_instance.h | 8 ++++++++ include/send/send_create.d.ts | 6 +++++- include/send/send_create.h | 15 +++++++++++++-- include/send/send_instance.d.ts | 16 ++++++++++++++-- include/structures/audio_frame.d.ts | 6 +++++- include/structures/video_frame.d.ts | 25 ++++++++++++++++++++++++- src/send/send_create.cpp | 9 +++++++-- src/send/send_instance.cpp | 2 +- 11 files changed, 96 insertions(+), 10 deletions(-) diff --git a/include/find/find_sources.d.ts b/include/find/find_sources.d.ts index 8d95a4e..4d9ef1e 100644 --- a/include/find/find_sources.d.ts +++ b/include/find/find_sources.d.ts @@ -1,3 +1,8 @@ import type { SourceInstance } from './source_instance'; +/** + * Calls the NDI API to retrieve a list of {@link SourceInstance}s + * exposed into the network. + * @param timeout The maximum timeout to keep waiting for the list of sources + */ export function findSources (timeout?: number): Promise; diff --git a/include/find/find_sources.h b/include/find/find_sources.h index b7ca2d9..5327d3b 100644 --- a/include/find/find_sources.h +++ b/include/find/find_sources.h @@ -3,6 +3,13 @@ #ifndef _SRC_FIND_FIND_SOURCES_H_ #define _SRC_FIND_FIND_SOURCES_H_ +/** + * Calls `NDIlib_find_get_current_sources` and retrieves the list of + * the available sources to be retrieved. + * + * If no sources are available, or the `NDIlib_find_wait_for_sources` + * call fails, retrieves an empty list. + */ Napi::Value FindSources(const Napi::CallbackInfo&); #endif diff --git a/include/find/source_instance.d.ts b/include/find/source_instance.d.ts index b273a9b..e8195fd 100644 --- a/include/find/source_instance.d.ts +++ b/include/find/source_instance.d.ts @@ -1,9 +1,16 @@ import { TallyState } from '../structures/tally_state'; +/** + * An instance of an NDI (sender/receiver) source + */ export interface SourceInstance { + /** Sets the tally state of the source instance */ setTally (tallyState: TallyState): void; + /** Retrieves the IP Address of the instance */ get ipAddress(): string; + /** Retrieves the name of the instance */ get name(): string; + /** Retrieves the URL Address of the instance */ get urlAddress(): string; } diff --git a/include/find/source_instance.h b/include/find/source_instance.h index 791bdd3..b8ecf23 100644 --- a/include/find/source_instance.h +++ b/include/find/source_instance.h @@ -4,19 +4,27 @@ #ifndef _SRC_STRUCTURES_SOURCE_INSTANCE_H_ #define _SRC_STRUCTURES_SOURCE_INSTANCE_H_ +/** + * An instance of an NDI (send/recv) source + */ class SourceInstance : public Napi::ObjectWrap { public: static void Init(Napi::Env env, Napi::Object exports); static Napi::Object New(Napi::Env env, NDIlib_source_t *ndiSourceInstance); static Napi::FunctionReference constructor; + /** Initializes an instance of a sender/receiver source */ SourceInstance(const Napi::CallbackInfo &info); ~SourceInstance(); + /** Sets the tally state of the source instance */ void SetTally(const Napi::CallbackInfo &info); + /** Retrieves the IP Address of the instance */ Napi::Value GetIpAddress(const Napi::CallbackInfo &info); + /** Retrieves the name of the instance */ Napi::Value GetName(const Napi::CallbackInfo &info); + /** Retrieves the URL Address of the instance */ Napi::Value GetUrlAddress(const Napi::CallbackInfo &info); diff --git a/include/send/send_create.d.ts b/include/send/send_create.d.ts index 9bc2a94..11f5ea1 100644 --- a/include/send/send_create.d.ts +++ b/include/send/send_create.d.ts @@ -1,4 +1,8 @@ -export interface SendCreate { +/** + * This structure holds the options used for creating a send (output) video + * source + */ +export interface SendCreateOptions { /** * The name of the send video source. */ diff --git a/include/send/send_create.h b/include/send/send_create.h index 49c4af3..1dfb97d 100644 --- a/include/send/send_create.h +++ b/include/send/send_create.h @@ -4,9 +4,20 @@ #ifndef _SRC_SEND_SEND_CREATE_H_ #define _SRC_SEND_SEND_CREATE_H_ -class SendCreate : Napi::Object { +/** + * This structure holds the options used for creating a send (output) video + * source + */ +class SendCreateOptions : Napi::Object { public: - SendCreate(const Napi::Object &object); + /** + * Constructs an instance of SendCreateOptions, which holds the + * options for creating a `SendInstance` + */ + SendCreateOptions(const Napi::Object &object); + /** + * A cast operator between this object and the `NDIlib_send_create_t` struct + */ operator NDIlib_send_create_t() const; }; diff --git a/include/send/send_instance.d.ts b/include/send/send_instance.d.ts index 73fdbf7..4f928c5 100644 --- a/include/send/send_instance.d.ts +++ b/include/send/send_instance.d.ts @@ -1,9 +1,21 @@ import { AudioFrame } from '../structures/audio_frame'; import { VideoFrame } from '../structures/video_frame'; -import { SendCreate } from './send_create'; +import { SendCreateOptions } from './send_create'; +/** + * A send (output) NDI instance + */ export class SendInstance { - initialize(initParameters: SendCreate): void; + /** + * Initializes an instance for sending video + * @param initParameters The options to initialize the instance + */ + initialize(initParameters: SendCreateOptions): void; + /** + * Sends a raw representation of frames (each one containing + * a {@link VideoFrame} and {@link AudioFrame}) into the NDI protocol. + * @param frames The video/audio frames to be sent into the network + */ send(frames: { video?: VideoFrame, audio?: AudioFrame diff --git a/include/structures/audio_frame.d.ts b/include/structures/audio_frame.d.ts index c8f4f7c..a752ded 100644 --- a/include/structures/audio_frame.d.ts +++ b/include/structures/audio_frame.d.ts @@ -1,3 +1,7 @@ +/** + * This structure represents the binary buffers for a multi-channel audio + * "frame" (being this frame a second of audio), with a specified sample rate. + */ export interface AudioFrame { /** * This is the current audio sample rate. For instance, this might be 44100, 48000 or 96000. @@ -7,7 +11,7 @@ export interface AudioFrame { /** * This is the floating-point audio data in planar format, split in channels, - * with each channel being a Float32Array. + * with each channel being a {@link Float32Array}. * * ```js * [ diff --git a/include/structures/video_frame.d.ts b/include/structures/video_frame.d.ts index 75da2d9..2307018 100644 --- a/include/structures/video_frame.d.ts +++ b/include/structures/video_frame.d.ts @@ -1,13 +1,32 @@ +/** + * This structure holds the metadata and binary + * representation of a single frame of video, that can + * be sent into an encoder or decoder + */ export interface VideoFrame { + /** The height of the video frame */ height: number; + /** The width of the video frame */ width: number; + /** + * The coulourspace format of the frame. This helps encoders/decoders + * figure out how to read the video buffer + */ colourSpace: VideoColourSpace; + /** + * This metadata is used for the video source to understand the + * frame is part of a video stream of a certain framerate. + */ framerate: VideoFramerate; - + /** A buffer-like binary representation of the video frame */ data: Buffer | Uint8Array; } +/** + * The possible values for the colourspace + * for which a certain frame is encoded + */ export enum VideoColourSpace { UYVY = 1, UYVA = 2, @@ -22,6 +41,10 @@ export enum VideoColourSpace { RGBX = 11, } +/** + * The possible values for the framerate at + * which a video stream is being encoded + */ export enum VideoFramerate { F24 = 1, F2498 = 2, diff --git a/src/send/send_create.cpp b/src/send/send_create.cpp index f873773..de407b5 100644 --- a/src/send/send_create.cpp +++ b/src/send/send_create.cpp @@ -3,11 +3,16 @@ using namespace std; -SendCreate::SendCreate( +/** + * Constructs an instance of SendCreateOptions, which holds the + * options for creating a `SendInstance` + */ +SendCreateOptions::SendCreateOptions( const Napi::Object &object) : Napi::Object(object) {} -SendCreate::operator NDIlib_send_create_t() const { + +SendCreateOptions::operator NDIlib_send_create_t() const { NDIlib_send_create_t sendCreateParams; if (!this->Has("name") || this->Get("name").IsUndefined()) { diff --git a/src/send/send_instance.cpp b/src/send/send_instance.cpp index ae01977..1e9eea3 100644 --- a/src/send/send_instance.cpp +++ b/src/send/send_instance.cpp @@ -27,7 +27,7 @@ void SendInstance::Initialize(const Napi::CallbackInfo &info) { // Initialize sendCreate parameters using the initParameters argument try { - NDIlib_send_create_t sendCreateParams = (SendCreate)info[0].ToObject(); + NDIlib_send_create_t sendCreateParams = (SendCreateOptions)info[0].ToObject(); this->ndiSendInstance = NDIlib_send_create(&sendCreateParams);