304 lines
13 KiB
C++
304 lines
13 KiB
C++
/**
|
|
*
|
|
* \file dnx_mxf_sdk.h
|
|
* Extension API allows to read\write DNxUncompressed and DNxHR/HD streams to/from MXF files according to SMPTE ST 377, RDD 50 and SMPTE ST 2019-4
|
|
*
|
|
* \copyright
|
|
* Copyright 2019 Avid Technology, Inc.
|
|
* All rights reserved.
|
|
*
|
|
* \par License
|
|
* The following programs are the sole property of Avid Technology, Inc.,
|
|
* and contain its proprietary and confidential information.
|
|
*
|
|
* \details mailto: partners@avid.com
|
|
*
|
|
*/
|
|
|
|
#ifndef DNXMXF_SDK_H
|
|
#define DNXMXF_SDK_H
|
|
|
|
#include <cstddef>
|
|
#include <cstdint>
|
|
|
|
#ifdef __cplusplus
|
|
extern "C"
|
|
{
|
|
#endif
|
|
|
|
/**
|
|
Error codes
|
|
*/
|
|
typedef enum DNXMXF_Err_t
|
|
{
|
|
DNXMXF_SUCCESS = 0, ///< API call succeeded
|
|
DNXMXF_FAIL = 1, ///< API call failed with message, use callback to get it
|
|
DNXMXF_INVALID_ARG = 2, ///< Invalid argument passed to API
|
|
DNXMXF_STRUCT_SIZE = 3, ///< structSize field is not equal to sizeof(struct) - probably header\lib version mismatch
|
|
DNXMXF_EOF = 4 ///< End of file reached
|
|
} DNXMXF_Err_t;
|
|
|
|
/**
|
|
MXF operational pattern(SMPTE ST 377 Section 8)
|
|
*/
|
|
typedef enum DNXMXF_OpPattern_t
|
|
{
|
|
DNXMXF_OP_INVALID = 0, ///< Invalid value
|
|
DNXMXF_OP_1a = 1, ///< According to SMPTE ST 378
|
|
DNXMXF_OP_Atom = 2, ///< According to SMPTE ST 390
|
|
} DNXMXF_OpPattern_t;
|
|
|
|
/**
|
|
MXF wrapping type(SMPTE ST 379)
|
|
*/
|
|
typedef enum DNXMXF_Wrap_t
|
|
{
|
|
DNXMXF_WRAP_INVALID = 0, ///< Invalid value
|
|
DNXMXF_WRAP_FRAME = 1, ///< Frame wrapping
|
|
DNXMXF_WRAP_CLIP = 2, ///< Clip wrapping
|
|
} DNXMXF_Wrap_t;
|
|
|
|
/**
|
|
Essence type
|
|
*/
|
|
typedef enum DNXMXF_Essence_t
|
|
{
|
|
DNXMXF_ESSENCE_INVALID = 0, ///< Invalid value
|
|
DNXMXF_ESSENCE_DNXUNCOMPRESSED = 1, ///< DNxUncompressed essence(see RDD 50)
|
|
DNXMXF_ESSENCE_DNXHR_HD = 2, ///< DNxHR/HD essence(see SMPTE ST 2019-1)
|
|
} DNXMXF_Essence_t;
|
|
|
|
/**
|
|
Property to override
|
|
*/
|
|
typedef enum DNXMXF_OverrideProperty_t
|
|
{
|
|
DNXMXF_OVERRIDEPROPERTY_INVALID = 0, ///< Invalid value
|
|
DNXMXF_OVERRIDEPROPERTY_COMP_DEPTH = 1, ///< MXF componentDepth(see SMPTE ST 377-1 G.2.26), uint32_t value expected
|
|
///< This property could be overriden only for DNxHR HQ, SQ, LB, valid values: 10, 12
|
|
} DNXMXF_OverrideProperty_t;
|
|
|
|
#pragma pack(push, 1)
|
|
|
|
/**
|
|
Rational number type(SMPTE ST 377 Section 4.3)
|
|
*/
|
|
typedef struct DNXMXF_Rational_t
|
|
{
|
|
unsigned int num; ///< Numerator
|
|
unsigned int den; ///< Denominator
|
|
} DNXMXF_Rational_t;
|
|
|
|
/**
|
|
Product Version type(SMPTE ST 377 Section 4.3)
|
|
*/
|
|
typedef struct DNXMXF_ProductVer_t
|
|
{
|
|
uint16_t major;
|
|
uint16_t minor;
|
|
uint16_t patch;
|
|
uint16_t build;
|
|
uint16_t release;
|
|
} DNXMXF_ProductVer_t;
|
|
|
|
/**
|
|
Timecode Component(SMPTE ST 377 Section B.17)
|
|
note: rounded timecode base automatically calculated according to frame rate
|
|
*/
|
|
typedef struct DNXMXF_TimeCodeComponent_t
|
|
{
|
|
uint8_t hours;
|
|
uint8_t minutes;
|
|
uint8_t seconds;
|
|
uint8_t frames;
|
|
bool dropFrame;
|
|
} DNXMXF_TimeCodeComponent_t;
|
|
|
|
/**
|
|
Type of client function to call when error occurs
|
|
\param[in] message Error message
|
|
\param[in] userData Pointer to the object from DNXMXF_Options_t userData field, might be useful if client wants to pass additional object into callback
|
|
*/
|
|
typedef void(*DNXMXF_ErrorCallback_t)(const char *message, void *userData);
|
|
|
|
/**
|
|
Reader\Writer options
|
|
*/
|
|
typedef struct DNXMXF_Options_t
|
|
{
|
|
size_t structSize; ///< Size of struct in bytes
|
|
void *userData; ///< Any client data to pass into callbacks
|
|
DNXMXF_ErrorCallback_t errCallback; ///< Client function to call when error occurs, if NULL errors will be ignored
|
|
} DNXMXF_Options_t;
|
|
|
|
/**
|
|
Params of MXF file for writer
|
|
*/
|
|
typedef struct DNXMXF_WriterParams_t
|
|
{
|
|
size_t structSize; ///< Size of struct in bytes
|
|
const wchar_t *filePath; ///< Path to mxf file to write
|
|
DNXMXF_OpPattern_t op; ///< Operational pattern to use
|
|
DNXMXF_Wrap_t wrapType; ///< MXF wrapping to use
|
|
DNXMXF_Rational_t frameRate; ///< Frame rate of mxf file
|
|
const wchar_t *companyName; ///< [required] Manufacturer of the equipment or application that created or modified the file(SMPTE ST 377 Section A.3)
|
|
const wchar_t *productName; ///< [required] Name of the application which created or modified this file(SMPTE ST 377 Section A.3)
|
|
const wchar_t *verString; ///< [required] Human readable name of this application version(SMPTE ST 377 Section A.3)
|
|
const wchar_t *productUID; ///< [required] An unique identification for the product which created this file(defined by the manufacturer)(SMPTE ST 377 Section A.3)
|
|
///< 16 bytes in hex separated by dots e.g. 00.00.00.00.00.00.00.00.00.00.00.00.00.00.00.00
|
|
const DNXMXF_ProductVer_t *productVer; ///< [optional] Version number of this application(SMPTE ST 377 Section A.3)
|
|
/* Without specifying aspectRatio, videoLineMap1, videoLineMap2 the library produces 'Closed/Incomplete' MXF */
|
|
/* Library is able to set videoLineMap1, videoLineMap2 for standard rasters itself, otherwise this is client's responsibility to provide proper values */
|
|
DNXMXF_Rational_t aspectRatio; ///< [best effort] Specifies the horizontal to vertical aspect ratio of the whole image(SMPTE ST 377 Section G.2.4)
|
|
uint32_t videoLineMap1; ///< [best effort] First active line in first field(SMPTE ST 377 Section G.2.12)
|
|
uint32_t videoLineMap2; ///< [best effort] First active line in second field(SMPTE ST 377 Section G.2.12)
|
|
DNXMXF_Essence_t essence; ///< [required] Type of essence to write
|
|
const DNXMXF_TimeCodeComponent_t *initialTimeCode; ///< [optional] Initial timecode of the timecode track(SMPTE ST 377 Section B.17). If NULL all values initialized to 0
|
|
|
|
// values below are 16 bytes in hex separated by dots e.g. 00.00.00.00.00.00.00.00.00.00.00.00.00.00.00.00
|
|
const wchar_t *transferCharacteristic; ///< [optional] Specifies the opto-eletric transfer characteristic(SMPTE ST 377 Section F.4.1)
|
|
const wchar_t *codingEquations; ///< [optional] Specifies the encoding equations to convert RGB image components to component color difference image components(SMPTE ST 377 Section F.4.1)
|
|
const wchar_t *colorPrimaries; ///< [optional] Specifies the color primaries(SMPTE ST 377 Section F.4.1)
|
|
} DNXMXF_WriterParams_t;
|
|
|
|
/**
|
|
Params of MXF file for reader
|
|
*/
|
|
typedef struct DNXMXF_ReaderParams_t
|
|
{
|
|
size_t structSize; ///< Size of struct in bytes
|
|
const wchar_t *filePath; ///< Path to mxf file to read
|
|
} DNXMXF_ReaderParams_t;
|
|
|
|
/**
|
|
Values to read from MXF file
|
|
*/
|
|
typedef struct DNXMXF_ReaderMetadata_t
|
|
{
|
|
size_t structSize; ///< Size of struct in bytes
|
|
wchar_t transferCharacteristic[48]; ///< Opto-eletric transfer characteristic(SMPTE ST 377 Section F.4.1)
|
|
wchar_t codingEquations[48]; ///< Encoding equations to convert RGB image components to component color difference image components(SMPTE ST 377 Section F.4.1)
|
|
wchar_t colorPrimaries[48]; ///< Color primaries(SMPTE ST 377 Section F.4.1)
|
|
DNXMXF_TimeCodeComponent_t initialTimeCode; ///< Initial timecode of the timecode track(SMPTE ST 377 Section B.17)
|
|
} DNXMXF_ReaderMetadata_t;
|
|
|
|
#pragma pack(pop)
|
|
|
|
typedef struct DNXMXF_Writer DNXMXF_Writer;
|
|
|
|
/**
|
|
Creates MXF writer object
|
|
\param[in] options Struct describing writer options, NULL is defaults
|
|
\param[in] params Params of mxf file to write
|
|
\param[out] writer Pointer to writer object
|
|
\return Error code
|
|
*/
|
|
DNXMXF_Err_t DNXMXF_CreateWriter(const DNXMXF_Options_t *options,
|
|
const DNXMXF_WriterParams_t *params,
|
|
DNXMXF_Writer **writer);
|
|
|
|
/**
|
|
Free memory used by MXF writer object
|
|
\param[in] writer Pointer to writer object
|
|
*/
|
|
void DNXMXF_DestroyWriter(DNXMXF_Writer *writer);
|
|
|
|
/**
|
|
Writes essence frame to MXF container
|
|
\param[in] writer Pointer to writer object
|
|
\param[in] src Pointer to essence frame data buffer
|
|
\param[in] srcSize Size of essence frame data buffer in bytes
|
|
\return Error code
|
|
*/
|
|
DNXMXF_Err_t DNXMXF_WriteFrame(DNXMXF_Writer *writer,
|
|
const void *src, unsigned int srcSize);
|
|
|
|
/**
|
|
Stop writing MXF file and flush all content
|
|
\param[in] writer Pointer to writer object
|
|
\return Error code
|
|
*/
|
|
DNXMXF_Err_t DNXMXF_FinishWrite(DNXMXF_Writer *writer);
|
|
|
|
/**
|
|
Overrides MXF property. Useful only in specific use-cases when client needs to override some default/autocalculated MXF properties
|
|
\param[in] writer Pointer to writer object
|
|
\param[in] prop MXF property to override
|
|
\param[in] value Pointer to property value
|
|
\param[in] valueSize Size of value in bytes(expected size depends on propetry)
|
|
\return Error code
|
|
*/
|
|
DNXMXF_Err_t DNXMXF_SetOverrideProperty(DNXMXF_Writer *writer,
|
|
DNXMXF_OverrideProperty_t prop,
|
|
const void *value, size_t valueSize);
|
|
|
|
typedef struct DNXMXF_Reader DNXMXF_Reader;
|
|
|
|
/**
|
|
Creates MXF reader object
|
|
\param[in] options Struct describing reader options, NULL is defaults
|
|
\param[in] params Reader params
|
|
\param[out] reader Pointer to reader object
|
|
\return Error code
|
|
*/
|
|
DNXMXF_Err_t DNXMXF_CreateReader(const DNXMXF_Options_t *options,
|
|
const DNXMXF_ReaderParams_t *params,
|
|
DNXMXF_Reader **reader);
|
|
|
|
/**
|
|
Free memory used by MXF reader object
|
|
\param[in] reader Pointer to reader object
|
|
*/
|
|
void DNXMXF_DestroyReader(DNXMXF_Reader *reader);
|
|
|
|
/**
|
|
Returns buffer size enough to keep any frame in MXF file
|
|
\param[in] reader Pointer to reader object
|
|
\param[out] maxBufSize Size of buffer in bytes
|
|
\return Error code
|
|
*/
|
|
DNXMXF_Err_t DNXMXF_MaxBufSize(DNXMXF_Reader *reader, unsigned int *maxBufSize);
|
|
|
|
/**
|
|
Returns count of frames in MXF file
|
|
\param[in] reader Pointer to reader object
|
|
\param[out] framesCount Count of frames
|
|
\return Error code
|
|
*/
|
|
DNXMXF_Err_t DNXMXF_FramesCount(DNXMXF_Reader *reader, unsigned int *framesCount);
|
|
|
|
/**
|
|
Set current read position to frame by index, useful for random access reading
|
|
\param[in] reader Pointer to reader object
|
|
\param[in] offset Number of frames to seek from origin
|
|
\param[in] origin Position used as reference for the offset (SEEK_SET, SEEK_CUR, SEEK_END - use <cstdio>)
|
|
\return Error code
|
|
*/
|
|
DNXMXF_Err_t DNXMXF_Seek(DNXMXF_Reader *reader, long int offset, int origin);
|
|
|
|
/**
|
|
Reads essence frame from MXF container
|
|
\param[in] reader Pointer to reader object
|
|
\param[in] dst Pointer to buffer to write frame into
|
|
\param[in] dstSize Size of buffer in bytes
|
|
\param[out] bytesWritten Actual frame size of dst in bytes
|
|
\return Error code, DNXMXF_EOF means all frames were read
|
|
*/
|
|
DNXMXF_Err_t DNXMXF_ReadFrame(DNXMXF_Reader *reader,
|
|
void *dst, unsigned int dstSize,
|
|
unsigned int *bytesWritten);
|
|
|
|
/**
|
|
Reads metadata values of MXF file
|
|
\param[in] reader Pointer to reader object
|
|
\param[out] metadata Pointer to metadata values
|
|
\return Error code
|
|
*/
|
|
DNXMXF_Err_t DNXMXF_ReadMetadata(DNXMXF_Reader *reader, DNXMXF_ReaderMetadata_t *metadata);
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
#endif
|