175 lines
7.3 KiB
C
175 lines
7.3 KiB
C
/*!
|
|
* @file ProResEncoder.h
|
|
*
|
|
* @brief ProRes encoding API.
|
|
*
|
|
* Copyright (c) 2009-2016 Apple Inc. All rights reserved.
|
|
*/
|
|
|
|
#ifndef PRORES_ENCODER_H
|
|
#define PRORES_ENCODER_H
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
|
|
/*! ProRes codec types */
|
|
typedef enum {
|
|
kPRType422HQ = 'apch', //!< ProRes 422 HQ (~220 Mbps at 1920x1080x29.97)
|
|
kPRType422 = 'apcn', //!< ProRes 422 (~145 Mbps at 1920x1080x29.97)
|
|
kPRType422LT = 'apcs', //!< ProRes 422 LT (~100 Mbps at 1920x1080x29.97)
|
|
kPRType422Proxy = 'apco', //!< ProRes 422 Proxy (~ 45 Mbps at 1920x1080x29.97)
|
|
kPRType4444 = 'ap4h', //!< ProRes 4444 (~330 Mbps at 1920x1080x29.97 excluding alpha)
|
|
kPRType4444XQ = 'ap4x' //!< ProRes 4444 XQ (~495 Mbps at 1920x1080x29.97 excluding alpha)
|
|
} PRCodecType;
|
|
|
|
|
|
/*! ProRes interlace encoding modes */
|
|
typedef enum {
|
|
kPRProgressiveScan = 0, //!< Progressive encoding mode
|
|
kPRInterlacedTopFieldFirst = 1, //!< Interlaced mode; first (top) image line belongs to first temporal field
|
|
kPRInterlacedBottomFieldFirst = 2 //!< Interlaced mode; second (bottom) image line belongs to first temporal field
|
|
} PRInterlaceMode;
|
|
|
|
|
|
#ifndef PR_PIXEL_FORMAT_DEFINED
|
|
/*! Source pixel formats */
|
|
typedef enum {
|
|
kPRFormat_2vuy = '2vuy', //!< 4:2:2 Y'CbCr 8-bit video range (http://developer.apple.com/library/mac/technotes/tn2162/)
|
|
kPRFormat_v210 = 'v210', //!< 4:2:2 Y'CbCr 10-bit video range (http://developer.apple.com/library/mac/technotes/tn2162/)
|
|
kPRFormat_v216 = 'v216', //!< 4:2:2 Y'CbCr 16-bit little endian video range (http://developer.apple.com/library/mac/technotes/tn2162/)
|
|
kPRFormat_y416 = 'y416', //!< 4:4:4:4 AY'CbCr 16-bit little endian full range alpha, video range Y'CbCr
|
|
kPRFormat_r4fl = 'r4fl', //!< 4:4:4:4 AY'CbCr 32-bit float (http://developer.apple.com/library/mac/technotes/tn2201/)
|
|
kPRFormat_R10k = 'R10k', //!< 4:4:4 Full-range (0-1023) RGBxx 10-bit RGB, 2 bits padding, 32-bit big endian word per pixel
|
|
kPRFormat_r210 = 'r210', //!< 4:4:4 Full-range (0-1023) xxRGB 10-bit RGB, 2 bits padding, 32-bit big endian word per pixel
|
|
kPRFormat_b64a = 'b64a' //!< 4:4:4:4 Full-range (0-65535) ARGB 16-bit big endian per component
|
|
} PRPixelFormat;
|
|
#define PR_PIXEL_FORMAT_DEFINED
|
|
#endif
|
|
|
|
|
|
/*!
|
|
* Represents an encoder instance created by PROpenEncoder() and disposed by
|
|
* PRCloseEncoder().
|
|
*/
|
|
typedef struct PREncoder* PREncoderRef;
|
|
|
|
|
|
/*!
|
|
* Specifies parameters to use for encoding a frame.
|
|
*/
|
|
struct PREncodingParams {
|
|
PRCodecType proResType; //!< Specifies HQ, standard, LT, or Proxy
|
|
PRInterlaceMode interlaceMode; //!< Specifies interlaced or progressive encoding mode
|
|
bool preserveAlpha; //!< When true, the alpha channel in 4:4:4:4 source buffers will be encoded (only applicable to kPRType4444).
|
|
};
|
|
typedef struct PREncodingParams PREncodingParams;
|
|
|
|
|
|
/*!
|
|
* Specifies a source frame to be encoded.
|
|
*/
|
|
struct PRSourceFrame {
|
|
const void* baseAddr; //!< Pointer to first pixel of source buffer (must be 16-byte aligned)
|
|
int rowBytes; //!< Number of bytes from first pixel of one line to first pixel of next line (must be multiple of 16)
|
|
PRPixelFormat format; //!< Pixel format of source buffer (2vuy, v210, or v216)
|
|
int width; //!< Frame width in pixels (must be multiple of 16)
|
|
int height; //!< Frame height in pixels
|
|
};
|
|
typedef struct PRSourceFrame PRSourceFrame;
|
|
|
|
|
|
/*!
|
|
* Utility routine that returns the maximum and target compressed frame sizes
|
|
* (in bytes) for the specified ProRes codec type and frame dimensions. The
|
|
* ProRes encoder attempts to encode each frame as close to the target size as
|
|
* possible, while never exceeding the maximum size.
|
|
*
|
|
* @param proResType Specifies HQ, standard, LT, Proxy, or 4444.
|
|
* @param preserveAlpha When true and proResType is kPRType4444,
|
|
* maxCompressedFrameSize is increased to
|
|
* accommodate an upper bound for the losslessly
|
|
* compressed alpha channel. This argument is
|
|
* ignored for 422 proResTypes.
|
|
* @param frameWidth Frame width in pixels.
|
|
* @param frameHeight Frame height in pixels.
|
|
* @param maxCompressedFrameSize The maximum size of a compressed frame.
|
|
* @param targetCompressedFrameSize The target size of a compressed frame.
|
|
*/
|
|
void
|
|
PRGetCompressedFrameSize(
|
|
PRCodecType proResType,
|
|
bool preserveAlpha,
|
|
int frameWidth,
|
|
int frameHeight,
|
|
int* maxCompressedFrameSize,
|
|
int* targetCompressedFrameSize);
|
|
|
|
|
|
/*!
|
|
* Opens an encoder instance and spawns "worker" threads. If a
|
|
* threadStartupCallback callback function is supplied, each worker
|
|
* thread will call this function upon startup to provide a way for you
|
|
* to set the threads' priorities.
|
|
*
|
|
* @param numThreads The number of simultaneous processing threads to spawn.
|
|
* Set this to 0 to have the encoder determine this
|
|
* automatically based on the number of processors in
|
|
* the system.
|
|
* @param threadStartupCallback An optional callback function for each
|
|
* thread to call upon startup. Set to NULL
|
|
* if no callback is needed.
|
|
*
|
|
* @return A reference to the instantiated encoder, or NULL on failure.
|
|
*/
|
|
PREncoderRef
|
|
PROpenEncoder(int numThreads, void (*threadStartupCallback)());
|
|
|
|
|
|
/*!
|
|
* Encodes a frame. It is the caller's responsibility to ensure that
|
|
* destinationPtr is a buffer of sufficient size to contain the compressed
|
|
* frame. The minimum required size is provided by the maxCompressedFrameSize
|
|
* value returned by the PRGetCompressedFrameSize() function.
|
|
*
|
|
* @param encoder An encoder instance returned by PROpenEncoder.
|
|
* @param encodingParams The parameters to use for encoding this frame.
|
|
* @param sourceFrame The source frame to encode.
|
|
* @param destinationPtr Location for encoded bitstream to be written.
|
|
* @param destinationSize Number of bytes available at destinationPtr.
|
|
* @param compressedFrameSize Returns the actual size of the compressed frame.
|
|
* @param allOpaqueAlpha Returns true if the encoded alpha channel is
|
|
* entirely opaque. If all frames are opaque, the
|
|
* QuickTime movie should be written with the
|
|
* 'depth' field of the image description set to 24.
|
|
*
|
|
* @return 0 if successful or a nonzero value if an error occurred.
|
|
*/
|
|
int
|
|
PREncodeFrame(
|
|
PREncoderRef encoder,
|
|
const PREncodingParams* encodingParams,
|
|
const PRSourceFrame* sourceFrame,
|
|
void* destinationPtr,
|
|
int destinationSize,
|
|
int* compressedFrameSize,
|
|
bool* allOpaqueAlpha);
|
|
|
|
|
|
/*!
|
|
* Closes the encoder, shuts down threads, and releases all resources
|
|
* associated with the encoder instance allocated in PROpenEncoder().
|
|
*
|
|
* @param encoder The encoder instance to dispose.
|
|
*/
|
|
void
|
|
PRCloseEncoder(PREncoderRef encoder);
|
|
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
#endif // PRORES_ENCODER_H
|