Blackmagic RAW SDK

Developer Information
Blackmagic
RAW SDK
July 2019
Contents
Blackmagic RAW SDK
Introduction and Overview 8
1.0 API Overview 8
1.1 Decoder Overview 8
1.2 Sidecar 8
2.0 Interface Overview 10
2.2 Clip Object 10
2.3 Frame Object 11
3.0 SDK Operations and flow 11
3.1 Manual Decoders 11
4.0 GPU Configuration 11
4.1 Pipeline iterators 12
4.2 Pipeline device iterators 12
4.3 Pipeline preparation 12
4.4 Multi GPU Devices 12
Recommended UI Controls and Behavior 13
Custom Gamma Controls 14
Basic Types 17
BlackmagicRawVariantType 20
BlackmagicRawResourceType 20
BlackmagicRawResourceFormat 21
BlackmagicRawResourceUsage 21
BlackmagicRawPipeline 21
BlackmagicRawInstructionSet 21
BlackmagicRawAudioFormat 22
BlackmagicRawResolutionScale 22
BlackmagicRawClipProcessingAttribute 22
BlackmagicRawFrameProcessingAttribute 23
BlackmagicRawInterop 23
Interface Reference 24
IBlackmagicRaw Interface 24
IBlackmagicRaw::OpenClip method 24
IBlackmagicRaw::SetCallback method 25
IBlackmagicRaw::PreparePipeline method 25
Contents 2
IBlackmagicRaw::PreparePipelineForDevice method 26
IBlackmagicRaw::FlushJobs method 26
IBlackmagicRawFactory Interface 26
IBlackmagicRawFactory::CreateCodec method 26
IBlackmagicRawFactory::CreatePipelineIterator method 27
IBlackmagicRawFactory::CreatePipelineDeviceIterator method 27
IBlackmagicRawPipelineIterator Interface 28
IBlackmagicRawPipelineIterator::Next method 28
IBlackmagicRawPipelineIterator::GetName method 28
IBlackmagicRawPipelineIterator::GetInterop method 28
IBlackmagicRawPipelineIterator::GetPipeline method 29
IBlackmagicRawPipelineDeviceIterator Interface 29
IBlackmagicRawPipelineDeviceIterator::Next method 29
IBlackmagicRawPipelineDeviceIterator::GetPipeline method 29
IBlackmagicRawPipelineDeviceIterator::GetInterop method 30
IBlackmagicRawPipelineDeviceIterator::CreateDevice method 30
IBlackmagicRawOpenGLInteropHelper Interface 30
IBlackmagicRawOpenGLInteropHelper::GetPreferredResourceFormat method 30
IBlackmagicRawOpenGLInteropHelper::SetImage method 31
IBlackmagicRawPipelineDevice Interface 31
IBlackmagicRawPipelineDevice::SetBestInstructionSet method 32
IBlackmagicRawPipelineDevice::SetInstructionSet method 32
IBlackmagicRawPipelineDevice::GetInstructionSet method 32
IBlackmagicRawPipelineDevice::GetIndex method 32
IBlackmagicRawPipelineDevice::GetName method 33
IBlackmagicRawPipelineDevice::GetInterop method 33
IBlackmagicRawPipelineDevice::GetPipeline method 33
IBlackmagicRawPipelineDevice::GetPipelineName method 34
IBlackmagicRawPipelineDevice::GetOpenGLInteropHelper method 34
IBlackmagicRawToneCurve Interface 34
IBlackmagicRawToneCurve::GetToneCurve method 35
IBlackmagicRawToneCurve::EvaluateToneCurve method 36
IBlackmagicRawConstants Interface 37
IBlackmagicRawConstants::GetClipProcessingAttributeRange method 37
IBlackmagicRawConstants::GetClipProcessingAttributeList method 38
IBlackmagicRawConstants::GetFrameProcessingAttributeRange method 38
IBlackmagicRawConstants::GetFrameProcessingAttributeList method 39
IBlackmagicRawConstants::GetISOListForAnalogGain method 39
Contents 3
IBlackmagicRawConfiguration Interface 40
IBlackmagicRawConfiguration::SetPipeline method 40
IBlackmagicRawConfiguration::GetPipeline method 41
IBlackmagicRawConfiguration::IsPipelineSupported method 41
IBlackmagicRawConfiguration::SetCPUThreads method 42
IBlackmagicRawConfiguration::GetCPUThreads method 42
IBlackmagicRawConfiguration::GetMaxCPUThreadCount method 42
IBlackmagicRawConfiguration::SetWriteMetadataPerFrame method 43
IBlackmagicRawConfiguration::GetWriteMetadataPerFrame method 43
IBlackmagicRawConfiguration::SetFromDevice method 43
IBlackmagicRawConfigurationEx Interface 44
IBlackmagicRawConfigurationEx::GetResourceManager method 44
IBlackmagicRawConfigurationEx::SetResourceManager method 44
IBlackmagicRawConfigurationEx::GetInstructionSet method 45
IBlackmagicRawConfigurationEx::SetInstructionSet method 45
IBlackmagicRawResourceManager Interface 45
IBlackmagicRawResourceManager::CreateResource method 46
IBlackmagicRawResourceManager::ReleaseResource method 46
IBlackmagicRawResourceManager::CopyResource method 47
IBlackmagicRawResourceManager::GetResourceHostPointer method 47
IBlackmagicRawMetadataIterator Interface 48
IBlackmagicRawMetadataIterator::Next method 48
IBlackmagicRawMetadataIterator::GetKey method 48
IBlackmagicRawMetadataIterator::GetData method 48
IBlackmagicRawClipProcessingAttributes Interface 49
IBlackmagicRawClipProcessingAttributes::GetClipAttribute method 49
IBlackmagicRawClipProcessingAttributes::SetClipAttribute method 49
IBlackmagicRawClipProcessingAttributes::GetPost3DLUT method 50
IBlackmagicRawPost3DLUT Interface 50
IBlackmagicRawPost3DLUT::GetName method 50
IBlackmagicRawPost3DLUT::GetTitle method 51
IBlackmagicRawPost3DLUT::GetSize method 51
IBlackmagicRawPost3DLUT::GetResourceGPU method 51
IBlackmagicRawPost3DLUT::GetResourceCPU method 52
IBlackmagicRawPost3DLUT::GetResourceSizeBytes method 52
IBlackmagicRawFrameProcessingAttributes Interface 52
IBlackmagicRawFrameProcessingAttributes::GetFrameAttribute method 53
IBlackmagicRawFrameProcessingAttributes::SetFrameAttribute method 53
Contents 4
IBlackmagicRawProcessedImage Interface 53
IBlackmagicRawProcessedImage::GetWidth method 54
IBlackmagicRawProcessedImage::GetHeight method 54
IBlackmagicRawProcessedImage::GetResource method 54
IBlackmagicRawProcessedImage::GetResourceType method 55
IBlackmagicRawProcessedImage::GetResourceFormat method 55
IBlackmagicRawProcessedImage::GetResourceSizeBytes method 55
IBlackmagicRawProcessedImage::GetResourceContextAndCommandQueue method 55
IBlackmagicRawJob Interface 56
IBlackmagicRawJob::Submit method 56
IBlackmagicRawJob::Abort method 57
IBlackmagicRawJob::SetUserData method 57
IBlackmagicRawJob::GetUserData method 57
IBlackmagicRawCallback Interface 58
IBlackmagicRawCallback::ReadComplete method 58
IBlackmagicRawCallback::DecodeComplete method 59
IBlackmagicRawCallback::ProcessComplete method 59
IBlackmagicRawCallback::TrimProgress method 59
IBlackmagicRawCallback::TrimComplete method 60
IBlackmagicRawCallback::SidecarMetadataParseWarning method 60
IBlackmagicRawCallback::SidecarMetadataParseError method 60
IBlackmagicRawCallback::PreparePipelineComplete method 61
IBlackmagicRawClipAudio Interface 61
IBlackmagicRawClipAudio::GetAudioFormat method 61
IBlackmagicRawClipAudio::GetAudioBitDepth method 62
IBlackmagicRawClipAudio::GetAudioChannelCount method 62
IBlackmagicRawClipAudio::GetAudioSampleRate method 62
IBlackmagicRawClipAudio::GetAudioSampleCount method 63
IBlackmagicRawClipAudio::GetAudioSamples method 63
IBlackmagicRawFrame Interface 64
IBlackmagicRawFrame::GetFrameIndex method 65
IBlackmagicRawFrame::GetTimecode method 65
IBlackmagicRawFrame::GetMetadataIterator method 65
IBlackmagicRawFrame::GetMetadata method 66
IBlackmagicRawFrame::SetMetadata method 66
IBlackmagicRawFrame::CloneFrameProcessingAttributes method 66
IBlackmagicRawFrame::SetResolutionScale method 67
IBlackmagicRawFrame::GetResolutionScale method 67
Contents 5
IBlackmagicRawFrame::SetResourceFormat method 67
IBlackmagicRawFrame::GetResourceFormat method 68
IBlackmagicRawFrame::CreateJobDecodeAndProcessFrame method 68
IBlackmagicRawFrameEx Interface 69
IBlackmagicRawFrameEx::GetBitStreamSizeBytes method 69
IBlackmagicRawFrameEx::GetProcessedImageResolution method 69
IBlackmagicRawManualDecoderFlow1 Interface 70
IBlackmagicRawManualDecoderFlow1::PopulateFrameStateBuffer method 70
IBlackmagicRawManualDecoderFlow1::GetFrameStateSizeBytes method 71
IBlackmagicRawManualDecoderFlow1::GetDecodedSizeBytes method 71
IBlackmagicRawManualDecoderFlow1::GetProcessedSizeBytes method 72
IBlackmagicRawManualDecoderFlow1::GetPost3DLUTSizeBytes method 72
IBlackmagicRawManualDecoderFlow1::CreateJobDecode method 73
IBlackmagicRawManualDecoderFlow1::CreateJobProcess method 73
IBlackmagicRawManualDecoderFlow2 Interface 74
IBlackmagicRawManualDecoderFlow2::PopulateFrameStateBuffer method 75
IBlackmagicRawManualDecoderFlow2::GetFrameStateSizeBytes method 75
IBlackmagicRawManualDecoderFlow2::GetDecodedSizeBytes method 76
IBlackmagicRawManualDecoderFlow2::GetWorkingSizeBytes method 76
IBlackmagicRawManualDecoderFlow2::GetProcessedSizeBytes method 76
IBlackmagicRawManualDecoderFlow2::GetPost3DLUTSizeBytes method 77
IBlackmagicRawManualDecoderFlow2::CreateJobDecode method 77
IBlackmagicRawManualDecoderFlow2::CreateJobProcess method 78
IBlackmagicRawClip Interface 79
IBlackmagicRawClip::GetWidth method 80
IBlackmagicRawClip::GetHeight method 80
IBlackmagicRawClip::GetFrameRate method 80
IBlackmagicRawClip::GetFrameCount method 81
IBlackmagicRawClip::GetTimecodeForFrame method 81
IBlackmagicRawClip::GetMetadataIterator method 81
IBlackmagicRawClip::GetMetadata method 82
IBlackmagicRawClip::SetMetadata method 82
IBlackmagicRawClip::GetCameraType method 82
IBlackmagicRawClip::CloneClipProcessingAttributes method 83
IBlackmagicRawClip::GetMulticardFileCount method 83
IBlackmagicRawClip::IsMulticardFilePresent method 83
IBlackmagicRawClip::GetSidecarFileAttached method 84
IBlackmagicRawClip::SaveSidecarFile method 84
Contents 6
IBlackmagicRawClip::ReloadSidecarFile method 84
IBlackmagicRawClip::CreateJobReadFrame method 85
IBlackmagicRawClip::CreateJobTrim method 85
IBlackmagicRawClipEx Interface 86
IBlackmagicRawClipEx::GetMaxBitStreamSizeBytes method 86
IBlackmagicRawClipEx::GetBitStreamSizeBytes method 87
IBlackmagicRawClipEx::CreateJobReadFrame method 87
IBlackmagicRawClipEx::QueryTimecodeInfo method 88
Contents 7
Introduction and Overview
1.0 API Overview
The Blackmagic RAW SDK provides a highly optimised decoder and image processing pipeline.
Blackmagic RAW API
DECODER .Braw .Sidecar

Reader Reader
SSE AVX AVX2
METAL CUDA OPENCL
Available on Mac, Windows, and Linux platforms, the SDK supports supports multiple CPU
architectures and multiple GPU APIs in order to take full advantage of your machine.
The goal is to provide an easy to use yet powerful SDK, which will utilise cross-platform efficient
decoding of .braw files produced by Blackmagic Cameras.
1.1 Decoder Overview

The CPU decoder has been designed to scale from laptops to workstations with a large number of
cores. The CPU decoder will utilise SSE, AVX and AVX2 instructions if available. The user has
control to limit the CPU decoder to fewer threads if desired.
There are several GPU decoders available, including Metal, CUDA, and OpenCL. The final
processed image from each decoder will be provided in a buffer object native to the respective GPU
API. This will allow quick access for further processing or display.
The GPU decoders are dynamically loaded, meaning they will require the system to have the
relevant APIs installed in order to function.
The SDK has been designed for multi-GPU and multi-process capabilities allowing high level
workstations to use all the resources available in the system.
1.2 Sidecar
A .sidecar file may be used, storing any metadata that is modified after the original .braw file
is produced. The intent here is to not modify the original .braw file. This sidecar file can be manually
deleted if the user wants to restore the movie metadata to its original state.
When metadata or image processing values (such as white balance) are modified via the SDK, the
user can then choose to save this data to the sidecar file. Now when the movie is loaded (potentially
in a different application) the sidecar file be applied and the picture will look consistent.
At this time, the user can run the ‘trim’ operation which will bake the sidecar changes into a newly
created .braw file saved to disk. This can be run on any frame range right down to a single frame
which produces handy images to pass between colleagues.
The .sidecar file is stored as a text JSON file, allowing users to manually edit or use external tools if
they wish to modify it.

3DLUT data (in DaVinci Resolve .cube format) can be embedded into .braw clips and also be stored
in sidecar files. This provides additional ways for 3DLUTs to travel with .braw clips to maintain
consistency in viewing. The SDK allows users to optionally process the clip with the embedded
3DLUT in the clip itself, from the sidecar, or for 3DLUT processing to be disabled. Tetrahedral
interpolation is used for both GPU and CPU pipelines.
An example sidecar with an identity 3DLUT follows. The information has been truncated for brevity.
{
“tone_curve_contrast” : 1.450000,
“tone_curve_saturation” : 1.150000,
“tone_curve_midpoint” : 0.409000,
“tone_curve_highlights” : 0.600000,
“tone_curve_shadows” : 1.800000,
“tone_curve_black_level” : 0.000000,
“tone_curve_white_level” : 1.000000,
“tone_curve_video_black_level” : 1,
“highlight_recovery” : 1,
“viewing_gamma” : “Blackmagic Design Custom”,
“viewing_gamut” : “Blackmagic Design”,
“exposure”: {
“14:57:33:00” : 0.200000
},
“white_balance_kelvin”: {
“14:57:33:00” : 4520
},
“white_balance_tint”: {
“14:57:33:00” : 5
},
“iso”: {
“14:57:33:00” : 500
},
“post_3dlut_mode” : “Sidecar”,
“post_3dlut_sidecar_name” : “Identity3DLUT.cube”,
“post_3dlut_sidecar_title” : “My Identity 3D LUT”,
“post_3dlut_sidecar_size” : 33,
“post_3dlut_sidecar_data” : “0.0000000000 0.0000000000 0.0000000000
0.0312500000 0.0000000000 0.0000000000
0.0625000000 0.0000000000 0.0000000000
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
0.9375000000 1.0000000000 1.0000000000
0.9687500000 1.0000000000 1.0000000000
1.0000000000 1.0000000000 1.0000000000”

}

2.0 Interface Overview
This chapter covers a basic overview of the interfaces used via the Blackmagic RAW API
IBlackmagicRawFactory
IBlackmagicRaw
IBlackmagicRawConstants
IBlackmagicRawConfiguration
IBlackmagicRawClip
IBlackmagicRawMetadataIterator
IBlackmagicRawClipAudio
IBlackmagicRawClipProcessingAttributes
IBlackmagicRawFrame
IBlackmagicRawMetadataIterator
IBlackmagicRawFrameProcessingAttributes
IBlackmagicRawProcessedImage
IBlackmagicRawFactory is the API entry point. From here the user creates a IBlackmagicRaw object.
This object owns a single decoder instance.
This object can be configured via IBlackmagicRawConfiguration allowing the user to define CPU
constraints or set up the SDK to use desired GPU APIs.
After completing the above steps, the user can start opening clips. Once the first clip has been
opened, the decoder is started and any further configuration changes will be discarded.
2.2 Clip Object

Once a clip is opened its components can now be accessed. A metadata iterator is available
to provide all clip-level metadata (see frame-level metadata in 2.4 below).
Clip audio & clip-level processing attributes can also be accessed. The clip-level processing
attributes allow the user to modify fields such as displayed gamma, displayed gamut, Blackmagic
colour science generation and custom gamma parameters.
Finally with the clip object we create an asynchronous job to read a frame from the clip.
This will provide a frame object.

2.3 Frame Object
A frame object provides access to frame-level metadata & frame-level processing attributes. The
frame-level processing attributes allow the user to modify fields that can change on a per-frame
basis. They include white balance tint/kelvin, exposure & ISO.
The user can also specify output scale & the desired pixel format of the processed image which is
produced upon request from the frame.
Once ready, the user creates an asynchronous job to produce the processed image. This image is
then ready for display.
3.0 SDK Operations and flow

This chapter provides a brief explanation of how the above objects work together to
produce a final image.
The SDK provides three main operations, read, decode and process. The read operation is reading
the compressed image from an opened IBlackmagicRawClip file into a IBlackmagicRawFrame. The
decode operation decodes this compressed image format and prepares it for processing. The
process operation applies colour processing (such as white balancing, exposure) and provides the
final image.
Each of these operations are asynchronous and occur across multiple CPU threads / GPU contexts.
By default this is all handled internally to provide an easy yet efficient solution.
The flow described above is: open a clip, read a frame, decode and process frame:
IBlackmagicRawClip IBlackmagicRawFrame IBlackmagicRawProcessedImage
ReadFrame() DecodeAndProcess()
3.1 Manual Decoders

There are manual decoders available which split the 3 above operations into separated user-driven
steps. These are for advanced use and provide closer access to buffer control, memory use, GPU
contexts and so forth, should your application require it.
Please see the IBlackmagicRawManualDecoder* interfaces available in the API header to

use this approach.
4.0 GPU Configuration

When utilising the GPU, at configuration time (described above in section 2.0) the GPU devices must
be provided to the IBlackmagicRawConfiguration object. This includes passing in a context and
commandQueue for the desired device.
To create a context and commandQueue the user needs to utilise their desired compute API library
(i.e. Metal, CUDA or OpenCL).
To make this easier for the user, Blackmagic RAW SDK offers pipeline and device iterators. These
allow creation of devices in an abstract way, removing the need to deal directly with compute APIs.

4.1 Pipeline iterators
Iterating through the available pipelines will allow your application to query for the presence and
usability of CUDA, Metal, OpenCL and CPU based decoder pipelines. Each of these may be used to
create a pipeline device iterator, with which associated compatible devices may be created.
Using this interface allows applications to check for various compute APIs without the need to set-up
and call any of the API functions and hence removes the requirement of linking against API libraries
and associated dependencies explicitly.
The pipeline iterator is created via IBlackmagicRawFactory’s CreatePipelineIterator method.
4.2 Pipeline device iterators

The pipeline device iterator (IBlackmagicRawPipelineDeviceIterator) is used to iterate over all
devices that a specific pipeline supports.
Once a (IBlackmagicRawPipelineDevice) device has been created via the device iterator, it may be
used to configure a decoder with the SetFromDevice method of IBlackmagicRawConfiguration.
This is equivalent to, but more convenient than, querying the context and command queue from the
device with the GetPipeline method and providing these parameters to the decoder configuration
via SetPipeline.
The context and command queue owned by a device are compute-level API objects
that are used directly by the decoder. The life-time of these compute-level API objects
must outlive that of the decoder, therefore the device instance MUST outlive the
decoder instance.
4.3 Pipeline preparation

A pipeline may have resources which require preparation, such as compilation or binding of GPU
kernels to a device. The SDK provides a mechanism whereby the user may prepare these resources
ahead of time, removing any stall necessitated by the use of these resources in the actual
decoding process.
The preparation of these resources is a potentially time-consuming process and as such is executed
asynchronously. The callback interface has a method (PreparePipelineComplete) to allow the user to
respond to the completion of a pipeline preparation.
A pipeline is prepared on IBlackmagicRaw with either PreparePipeline (providing context and

command queue) or PreparePipelineForDevice (providing an instance of
IBlackmagicRawPipelineDevice), noting that the pipeline configuration MUST have been set prior.
4.4 Multi GPU Devices

When using multiple GPUs, a default GPU device is provided to the
IBlackmagicRawConfiguration object.
Taking advantage of the manual decoders (specified in section 3.1 above) allows the user to
distribute decoding operations across multiple devices.

Recommended UI Controls and Behavior
Decode Quality
Type: Drop down selector
Default: Full Res.
Options: – Full Res.

ͽͽ 1/2 Res.
ͽͽ 1/4 Res.
ͽͽ 1/8 Res.
Color Science Version

Default: Read from metadata
Options: Use IBlackmagicRawConstants::GetClipProcessingAttributeList()

- blackmagicRawClipProcessingAttributeColorScienceGen
Color Space/Gamut
Default: Read from metadata

- blackmagicRawClipProcessingAttributeGamut
Gamma
Default: Read from metadata.

- blackmagicRawClipProcessingAttributeGamma
ISO
Options: Use IBlackmagicRawConstants::GetFrameProcessingAttributeRange()

- blackmagicRawFrameProcessingAttributeISO
Exposure
Type: Slider
Default: 0.
Range: Use IBlackmagicRawConstants::GetFrameProcessingAttributeRange()

- blackmagicRawFrameProcessingAttributeExposure
Recommended UI Controls and Behavior 13

Color Temp
Type: Slider
Default: 5600

- blackmagicRawFrameProcessingAttributeWhiteBalanceKelvin
Tint
Type: Slider
Default: 10

- blackmagicRawFrameProcessingAttributeWhiteBalanceTint
Highlight Recovery
Type: Checkbox
Default: Off
Export Frame
Type: Button
Exports a single frame of the currently viewed video frame.
Update Sidecar
Type: Button
Saves sidecar file with the currently set parameters for the clip.
Custom Gamma Controls

Custom gamma controls should only be enabled and selectable for the following gamma selections:
Blackmagic Design Film

Blackmagic Design Extended Video
Blackmagic Design Custom
Note: Blackmagic Design Video should have the custom gamma controls DISABLED.
When selecting Blackmagic Design Film or Blackmagic Design Extended Video the custom gamma
controls take on the values supplied by the SDK. When a user adjusts a custom gamma control
slider, the gamma selection should automatically change to Blackmagic Design Custom which
should be written with the current values shown in the UI. The user is now creating their own custom
gamma which can be stored.
The following image examples show the custom gamma controls selectable with Blackmagic Design
Film, and disabled with an incompatible gamma such as Rec.709.

Example: The custom gamma controls (last 3rd of the RAW panel)
are enabled and selectable with Blackmagic Design Extended Video.
Example: The custom gamma controls (last 3rd of the RAW panel) are
disabled with Blackmagic Design Video gamma.
Saturation
Type: Slider
Default: 1.0
Range: Use IBlackmagicRawConstants::GetClipProcessingAttributeList()

- blackmagicRawClipProcessingAttributeToneCurveSaturation
Contrast
Type: Slider
Default: 0.5

- blackmagicRawClipProcessingAttributeToneCurveContrast
Midpoint
Type: Slider
Default: 0.41

- blackmagicRawClipProcessingAttributeToneCurveMidpoint

Highlight Rolloff
Type: Slider
Default: 1.0

- blackmagicRawClipProcessingAttributeToneCurveHighlights
Shadow Rolloff
Type: Slider
Default: 1.0

- blackmagicRawClipProcessingAttributeToneCurveShadows
Black Level
Type: Slider
Default: 1.0

- blackmagicRawClipProcessingAttributeToneCurveBlackLevel
White Level
Type: Slider
Default: 1.0

- blackmagicRawClipProcessingAttributeToneCurveWhiteLevel
Set Video Black Level

Type: Checkbox
Default: Off
IBlackmagicRawToneCurve::EvaluateToneCurve()
The EvaluateToneCurve method can be used to return a buffer that can then be used to draw and
visualize the result of the custom gamma controls. This is particularly useful when users are creating
their own custom gammas. An example of such a UI is shown below:

3D LUT

- blackmagicRawClipProcessingAttributePost3DLUTMode
Example: For clips that have an embedded or sidecar 3DLUT available,

an “Apply LUT” checkbox and “LUT Source” dropdown are shown.
Basic Types
enum
The enumerator type is represented differently on each platform, using the most appropriate
system type:
Windows unsigned int
macOS uint32_t
Linux uint32_t
uuid
The Universally unique identifier type is represented differently on each platform, using the most
appropriate system type:
Windows GUID
macOS CFUUIDBytes
Linux GUID
Boolean
A boolean is represented differently on each platform, using the most appropriate system type:
Windows BOOL
macOS bool
Linux bool
Basic Types 17
int8_t
The signed 8 bit integer type is represented differently on each platform, using the most appropriate
system type:
Windows signed char
macOS int8_t
Linux int8_t
uint8_t
The unsigned 8 bit integer type is represented differently on each platform, using the most
Windows unsigned char
macOS uint8_t
Linux uint8_t
int16_t
The signed 16 bit integer type is represented differently on each platform, using the most
Windows short
macOS int16_t
Linux int16_t
uint16_t
Windows unsigned short
macOS uint16_t
Linux uint16_t
int32_t
Windows int
macOS int32_t
Linux int32_t
Basic Types 18
uint32_t
Windows unsigned int
macOS uint32_t
Linux uint32_t
int64_t
Windows long long
macOS int64_t
Linux int64_t
uint64_t
Windows unsigned long long
macOS uint64_t
Linux uint64_t
long
The long type is represented differently on each platform, using the most appropriate system type:
Windows LONG
macOS long
Linux long
string
Strings are represented differently on each platform, using the most appropriate system type:
Windows BSTR
macOS CFStringRef
Linux const char*
SafeArray
The SafeArray type is represented differently on each platform, using the most appropriate
system type:
macOS SafeArray*
Linux SafeArray*
Basic Types 19
SafeArrayData
The SafeArrayData type is represented differently on each platform, using the most appropriate
system type:
macOS CFMutableDataRef
Linux void*
Variant
The Variant type is represented differently on each platform, using the most appropriate
system type:
Windows VARIANT*
macOS Variant*
Linux Variant*
BlackmagicRawVariantType
Variant types that may be stored as metadata
Value
macOS
and
Key Linux Windows Description
blackmagicRawVariantTypeEmpty 0 VT_EMPTY Undefined type
blackmagicRawVariantTypeU8 1 VT_UI1 Unsigned 8 bit integer
blackmagicRawVariantTypeS16 2 VT_I2 Signed 16 bit integer
blackmagicRawVariantTypeS32 4 VT_I4 Signed 32 bit integer
Single precision 32 bit (IEEE

blackmagicRawVariantTypeFloat32 6 VT_R4
754) floating point number
blackmagicRawVariantTypeString 7 VT_BSTR String variable
blackmagicRawVariantTypeSafeArray 8 VT_SAFEARRAY Array variable
BlackmagicRawResourceType
Used in IBlackmagicRawResourceManager
Key Value Description
blackmagicRawResourceTypeBufferCPU ‘cpub' Page aligned CPU addressable memory
blackmagicRawResourceTypeBufferMetal ‘metb' Metal MTLBuffer
blackmagicRawResourceTypeBufferCUDA ‘cudb' CUDA CUdeviceptr device pointer
blackmagicRawResourceTypeBufferOpenCL ‘oclb' OpenCL cl_mem buffer object
Basic Types 20
BlackmagicRawResourceFormat
Used for resource allocation
blackmagicRawResourceFormatRGBAU8 ‘rgba' Unsigned 8bit interleaved RGBA
blackmagicRawResourceFormatBGRAU8 ‘bgra’ Unsigned 8bit interleaved BGRA
blackmagicRawResourceFormatRGBU16 '16il' Unsigned 16bit interleaved RGB
blackmagicRawResourceFormatRGBU16Planar ‘16pl' Unsigned 16bit planar RGB
blackmagicRawResourceFormatRGBF32 ‘f32s' Floating point interleaved RGB
blackmagicRawResourceFormatRGBF32Planar ‘f32p' Floating point planar RGB
BlackmagicRawResourceUsage
Used in IBlackmagicRawResourceManager
blackmagicRawResourceUsageReadCPUWriteCPU ‘rcwc' CPU readable and writable memory
blackmagicRawResourceUsageReadGPUWriteGPU ‘rgwg' GPU readable and writable memory
blackmagicRawResourceUsageReadGPUWriteCPU ‘rgwc' GPU readable, CPU writable memory
blackmagicRawResourceUsageReadCPUWriteGPU ‘rcwg' CPU readable, GPU writable memory
BlackmagicRawPipeline
Used in IBlackmagicRawConfiguration. Each pipeline has different mappings to
context/commandQueue
blackmagicRawPipelineCPU ‘cpub' None
CUDA pipeline, context/commandQueue

blackmagicRawPipelineCUDA ‘cuda'
map to CUcontext/CUstream
Metal pipeline, context/commandQueue

blackmagicRawPipelineMetal ‘metl'
map to nil/MTLCommandQueue
OpenCL pipeline, context/commandQueue

blackmagicRawPipelineOpenCL ‘opcl'
map to cl_context/cl_command_queue
BlackmagicRawInstructionSet
Used in IBlackmagicRawConfiguration
blackmagicRawInstructionSetSSE41 ‘se41' SSE 4.1 CPU Instruction Set
blackmagicRawInstructionSetAVX ‘avx_' AVX CPU Instruction Set
blackmagicRawInstructionSetAVX2 ‘avx2' AVX2 CPU Instruction Set
Basic Types 21
BlackmagicRawAudioFormat
Used in IBlackmagicRawFileAudio
blackmagicRawAudioFormatPCMLittleEndian ‘pcml’ PCM little endian audio
BlackmagicRawResolutionScale
Used in IBlackmagicRawFrame
blackmagicRawResolutionScaleFull ‘full' Full Resolution
blackmagicRawResolutionScaleHalf ‘half' Half height and width
blackmagicRawResolutionScaleQuarter ‘qrtr' Quarter height and width
blackmagicRawResolutionScaleEighth ‘eith' Eighth height and width
blackmagicRawResolutionScaleFullUpsideDown ‘lluf’ Full Resolution (renders upside-down)
Half height and width (renders

blackmagicRawResolutionScaleHalfUpsideDown ‘flah’
upside-down)
Quarter height and width (renders

blackmagicRawResolutionScaleQuarterUpsideDown ‘rtrq’
upside-down)
Eighth height and width (renders

blackmagicRawResolutionScaleEighthUpsideDown ‘htie’
upside-down)
BlackmagicRawClipProcessingAttribute
blackmagicRawClipProcessingAttributeColorScienceGen ‘csgn' Blackmagic Color Science generation
blackmagicRawClipProcessingAttributeGamma ‘gama' The gamma curve
blackmagicRawClipProcessingAttributeGamut ‘gamt' The color gamut
Contrast used in Blackmagic Design Custom

blackmagicRawClipProcessingAttributeToneCurveContrast ‘tcon'
Gamma
Saturation used in Blackmagic Design

blackmagicRawClipProcessingAttributeToneCurveSaturation ‘tsat'
Custom Gamma
Midpoint used in Blackmagic Design Custom

blackmagicRawClipProcessingAttributeToneCurveMidpoint ‘tmid'
Gamma
Highlight rolloff used in Blackmagic Design

blackmagicRawClipProcessingAttributeToneCurveHighlights ‘thih'
Custom Gamma
Shadow rolloff used in Blackmagic Design

blackmagicRawClipProcessingAttributeToneCurveShadows ‘tsha'
Custom Gamma
VideoBlackLevel used in Blackmagic Design

blackmagicRawClipProcessingAttributeToneCurveVideoBlackLevel ‘tvbl'
Custom Gamma
Basic Types 22
BlackLevel used in Blackmagic Design

blackmagicRawClipProcessingAttributeToneCurveBlackLevel ‘tblk'
Custom Gamma
WhiteLevel used in Blackmagic Design

blackmagicRawClipProcessingAttributeToneCurveWhiteLevel ‘twit'
Custom Gamma
blackmagicRawClipProcessingAttributeHighlightRecovery ‘hlry' Is highlight recovery enabled
Analog Gain set at record time, cannot be

blackmagicRawClipProcessingAttributeAnalogGain ‘gain’
changed
Is the Post 3D LUT being applied embedded,

blackmagicRawClipProcessingAttributePost3DLUTMode 'lutm'
sidecar or disabled
blackmagicRawClipProcessingAttributeEmbeddedPost3DLUTName 'emln' Name of embedded 3D LUT
blackmagicRawClipProcessingAttributeEmbeddedPost3DLUTTitle 'emlt' Title of embedded 3D LUT
blackmagicRawClipProcessingAttributeEmbeddedPost3DLUTSize 'emls' Size of embedded 3D LUT
blackmagicRawClipProcessingAttributeEmbeddedPost3DLUTData 'emld' Float array of embedded 3D LUT data
blackmagicRawClipProcessingAttributeSidecarPost3DLUTName 'scln' Name of sidecar 3D LUT
blackmagicRawClipProcessingAttributeSidecarPost3DLUTTitle 'sclt' Title of sidecar 3D LUT
blackmagicRawClipProcessingAttributeSidecarPost3DLUTSize 'scls' Size of sidecar 3D LUT
blackmagicRawClipProcessingAttributeSidecarPost3DLUTData 'scld' Float array of sidecar 3D LUT data
BlackmagicRawFrameProcessingAttribute
The white balance Kelvin

blackmagicRawFrameProcessingAttributeWhiteBalanceKelvin ‘wbkv'
value
blackmagicRawFrameProcessingAttributeWhiteBalanceTint ‘wbtn' The white balance Tint value
The linear exposure

blackmagicRawFrameProcessingAttributeExposure ‘expo'
adjustment value (in stops)
blackmagicRawFrameProcessingAttributeISO ‘fiso' The ISO gamma curve
BlackmagicRawInterop
blackmagicRawInteropNone 'none' None
blackmagicRawInteropOpenGL 'opgl' None
Basic Types 23
Interface Reference
IBlackmagicRaw Interface
Each codec interface will have its own memory storage and decoder. When decoding multiple clips
via one codec, first in first out ordering will apply
Related Interfaces
Interface Interface ID
IBlackmagicRawConfiguration IID_IBlackmagicRawConfiguration
IBlackmagicRawConfigurationEx IID_IBlackmagicRawConfigurationEx
IBlackmagicRawConstants IID_IBlackmagicRawConstants
IBlackmagicRawManualDecoderFlow1 IID_IBlackmagicRawManualDecoderFlow1
IBlackmagicRawManualDecoderFlow2 IID_IBlackmagicRawManualDecoderFlow2
IBlackmagicRawToneCurve IID_IBlackmagicRawToneCurve
Public Member Functions
Method Description
OpenClip Opens a clip
SetCallback Registers a callback with the codec object
Asynchronously prepares the current pipeline for

decoding, calling the registered callback's
PreparePipelineComplete() method upon completion.
PreparePipeline
This reduces the potential performance impact of
decoding the first frame due to on-demand GPU kernel
compilation.
Asynchronously prepares the current pipeline for

decoding, calling the registered callback's
PreparePipelineComplete() method upon completion.
PreparePipelineForDevice
This reduces the potential performance impact of
decoding the first frame due to on-demand GPU kernel
compilation.
Blocking call which will only return once all jobs have
FlushJobs
been completed
IBlackmagicRaw::OpenClip method
Opens a clip
Syntax
HRESULT OpenClip
(string fileName,IBlackmagicRawClip** clip)
Parameters
Name Direction Description
fileName in File name on disk of clip to open
clip out Returned object with opened clip
Return Values
If the method succeeds, the return value is S_OK. E_POINTER is returned when clip is NULL,
E_INVALIDARG is returned when fileName is invalid, E_FAIL is returned if the clip failed to open.
IBlackmagicRaw::SetCallback method
Registers a callback with the codec object
Syntax
HRESULT SetCallback (IBlackmagicRawCallback* callback)
Parameters
callback in your callback object
Return Values
If the method succeeds, the return value is S_OK.
IBlackmagicRaw::PreparePipeline method
Asynchronously prepares the current pipeline for decoding, calling the registered callback’s
PreparePipelineComplete() method upon completion. This reduces the potential performance
impact of decoding the first frame due to on-demand GPU kernel compilation.
Syntax
HRESULT PreparePipeline (
void* pipelineContext,
void* pipelineCommandQueue,
void* userData)
Parameters
Pipeline for which to prepare. This must be the same as

pipeline in the current pipeline and is provided for validation
purposes
Context to use for preparation. For CPU/CUDA/Metal/

pipelineContext in
OpenCL, this maps to null/CUcontext/null/cl_context
Command queue to use for preparation. For CPU/

pipelineCommandQueue in CUDA/Metal/OpenCL, this maps to null/CUstream/
MTLCommandQueue/cl_command_queue
User data to pass through to the callback's

userData in
PreparePipelineComplete() method
Return Values
IBlackmagicRaw::PreparePipelineForDevice method
Asynchronously prepares the current pipeline for decoding, calling the registered callback’s
PreparePipelineComplete() method upon completion. This reduces the potential performance impact
of decoding the first frame due to on-demand GPU kernel compilation.
Syntax
HRESULT PreparePipelineForDevice(IBlackmagicRawPipelineDevice*
pipelineDevice,
void* userData)
Parameters
pipelineDevice in The device to use for preparation
User data to pass through to the callback's

userData in
PreparePipelineComplete() method
Return Values
IBlackmagicRaw::FlushJobs method
Blocking call which will only return once all jobs have been completed
Syntax
HRESULT FlushJobs()
Return Values
IBlackmagicRawFactory Interface
Use this to create one or more Codec objects
Method Description
CreateCodec Create a codec from the factory
CreatePipelineIterator Create a pipeline iterator from the factory
CreatePipelineDeviceIterator Create a pipeline device iterator from the factory
IBlackmagicRawFactory::CreateCodec method
Create a codec from the factory
Syntax
HRESULT CreateCodec (IBlackmagicRaw** codec)
Parameters
codec out Returned codec object
Return Values
If the method succeeds, the return value is S_OK. E_POINTER is returned when codec is NULL,
E_FAIL is returned if the codec failed to create.
IBlackmagicRawFactory::CreatePipelineIterator method
Create a pipeline iterator from the factory
Syntax
HRESULT CreatePipelineIterator(
BlackmagicRawInterop interop,
IBlackmagicRawPipelineIterator**
pipelineIterator)
Parameters
Interoperability (with other APIs) required from the

interop in
pipeline
pipelineIterator out The created pipeline iterator
Return Values
If the method succeeds, the return value is S_OK. E_POINTER is returned when
pipelineIterator is NULL.
IBlackmagicRawFactory::CreatePipelineDeviceIterator method
Create a pipeline device iterator from the factory
Syntax
HRESULT CreatePipelineDeviceIterator(
BlackmagicRawPipeline pipeline,
BlackmagicRawInterop interop,
IBlackmagicRawPipelineDeviceIterator**
deviceIterator)
Parameters
pipeline in The pipeline from which to query the available devices
Interoperability (with other APIs) required from the

interop in
pipeline and devices
deviceIterator out The created pipeline device iterator
Return Values
deviceIterator is NULL.
IBlackmagicRawPipelineIterator Interface
Use this to determine pipelines available for use on the system
Method Description
Next Step to next pipeline entry. S_FALSE is returned when called on last entry
GetName Get the name of the pipeline
GetInterop Get the interoperability of the pipeline
GetPipeline Get the pipeline
IBlackmagicRawPipelineIterator::Next method
Step to next pipeline entry. S_FALSE is returned when called on last entry
Syntax
HRESULT Next()
Return Values
If the method succeeds, the return value is S_OK or S_FALSE. S_FALSE is returned when Next() is
called on the last element. E_FAIL is returned when Next() is called after the last element.
IBlackmagicRawPipelineIterator::GetName method
Get the name of the pipeline
Syntax
HRESULT GetName(string* pipelineName)
Parameters
pipelineName out –
Return Values
pipelineName is NULL.
IBlackmagicRawPipelineIterator::GetInterop method
Get the interoperability of the pipeline
Syntax
HRESULT GetInterop(BlackmagicRawInterop* interop)
Parameters
interop out –
Return Values
If the method succeeds, the return value is S_OK. E_POINTER is returned when interop is NULL.
IBlackmagicRawPipelineIterator::GetPipeline method
Get the pipeline
Syntax
HRESULT GetPipeline(BlackmagicRawPipeline* pipeline)
Parameters
pipeline out –
Return Values
If the method succeeds, the return value is S_OK. E_POINTER is returned when pipeline is NULL.
IBlackmagicRawPipelineDeviceIterator Interface
Use this to determine pipeline devices available for use on the system
Method Description
Next Step to next device entry, will return S_FALSE when called on last entry
GetPipeline Get the pipeline
GetInterop Get the interoperability of the device's pipeline
CreateDevice Create the pipeline device (container for context and command queue)
IBlackmagicRawPipelineDeviceIterator::Next method
Step to next device entry, will return S_FALSE when called on last entry
Syntax
HRESULT Next()
Return Values
IBlackmagicRawPipelineDeviceIterator::GetPipeline method
Get the pipeline
Syntax
HRESULT GetPipeline(BlackmagicRawPipeline* pipeline)
Parameters
pipeline out –
Return Values
If the method succeeds, the return value is S_OK. E_POINTER is returned when pipeline is NULL.
IBlackmagicRawPipelineDeviceIterator::GetInterop method
Get the interoperability of the device’s pipeline
Syntax
Parameters
interop out –
Return Values
IBlackmagicRawPipelineDeviceIterator::CreateDevice method
Create the pipeline device (container for context and command queue)
Syntax
HRESULT CreateDevice(IBlackmagicRawPipelineDevice** pipelineDevice)
Parameters
pipelineDevice out –
Return Values
pipelineDevice is NULL.
IBlackmagicRawOpenGLInteropHelper Interface
Method Description
Gets the preferred resource format for interaction

GetPreferredResourceFormat
between the device and OpenGL
SetImage Copies the processed image into an OpenGL texture
IBlackmagicRawOpenGLInteropHelper::GetPreferredResourceFormat
method
Gets the preferred resource format for interaction between the device and OpenGL
Syntax
HRESULT GetPreferredResourceFormat(
BlackmagicRawResourceFormat* preferredFormat)
Parameters
preferredFormat out –
Return Values
preferredFormat is NULL.
IBlackmagicRawOpenGLInteropHelper::SetImage method
Copies the processed image into an OpenGL texture
Syntax
HRESULT SetImage(
IBlackmagicRawProcessedImage* processedImage,
uint32_t* openGLTextureName,
int32_t* openGLTextureTarget)
Parameters
processedImage in
openGLTextureName out name of OpenGL texture containing image
OpenGL target of texture containing image, typically

openGLTextureTarget out
GL_TEXTURE or GL_TEXTURE_RECTANGLE
Return Values
processedImage is NULL.
IBlackmagicRawPipelineDevice Interface
A device is essentially a container for a context and command queue associated with a pipeline. This
object is provided so the user need not deal directly with the underlying compute API in order to
provide context and command queue to the codec configuration. As such, the device instance
MUST outlive that of the codec instance on which the device is used.
Method Description
Sets the CPU instruction set of the device to be that representing the best
SetBestInstructionSet
capabilities of the system
SetInstructionSet Sets the CPU instruction set to use for the device
GetInstructionSet Gets the CPU instruction set of the device
Gets the index of the device in the pipeline's device list. This is typically
GetIndex
used to differentiate devices in multi-GPU configurations.
GetName Gets the name of the device
GetInterop Gets the API interoperability of the device
Gets the pipeline configuration information associated with the device.

These parameters may be provided to
GetPipeline
IBlackmagicRawConfiguration::SetPipeline.
IBlackmagicRawConfiguration::SetFromDevice may be a better option.
GetPipelineName Gets the name of the pipeline associated with the device
Creates an instance of a helper to get the results of a processed image as

GetOpenGLInteropHelper
an OpenGL texture
IBlackmagicRawPipelineDevice::SetBestInstructionSet method
Sets the CPU instruction set of the device to be that representing the best capabilities of the system
Syntax
HRESULT SetBestInstructionSet()
Return Values
This method returns S_OK.
IBlackmagicRawPipelineDevice::SetInstructionSet method
Sets the CPU instruction set to use for the device
Syntax
HRESULT SetInstructionSet(BlackmagicRawInstructionSet instructionSet)
Parameters
instructionSet in –
Return Values
If the method succeeds, the return value is S_OK. E_INVALIDARG is returned when instructionSet is
not a valid BlackmagicRawInstructionSet enumeration value. E_FAIL is returned if the user’s CPU
does not support the specified instruction set.
IBlackmagicRawPipelineDevice::GetInstructionSet method
Gets the CPU instruction set of the device
Syntax
HRESULT GetInstructionSet(BlackmagicRawInstructionSet* instructionSet)
Parameters
instructionSet out –
Return Values
instructionSet is NULL.
IBlackmagicRawPipelineDevice::GetIndex method
Gets the index of the device in the pipeline’s device list. This is typically used to differentiate devices
in multi-GPU configurations.
Syntax
HRESULT GetIndex(uint32_t* deviceIndex)
Parameters
deviceIndex out –
Return Values
deviceIndex is NULL.
IBlackmagicRawPipelineDevice::GetName method
Gets the name of the device
Syntax
HRESULT GetName(string* deviceName)
Parameters
deviceName out –
Return Values
deviceName is NULL.
IBlackmagicRawPipelineDevice::GetInterop method
Gets the API interoperability of the device
Syntax
Parameters
interop out –
Return Values
IBlackmagicRawPipelineDevice::GetPipeline method
Gets the pipeline configuration information associated with the device. These parameters may be
provided to IBlackmagicRawConfiguration::SetPipeline.
IBlackmagicRawConfiguration::SetFromDevice may be a better option.
Syntax
HRESULT GetPipeline(
BlackmagicRawPipeline* pipeline,
void** context,
void** commandQueue)
Parameters
pipeline out –
context out –
commandQueue out –
Return Values
If the method succeeds, the return value is S_OK. E_POINTER is returned when any of pipeline,
context and commandQueue is NULL.
IBlackmagicRawPipelineDevice::GetPipelineName method
Gets the name of the pipeline associated with the device
Syntax
HRESULT GetPipelineName(string* pipelineName)
Parameters
pipelineName out –
Return Values
pipelineName is NULL.
IBlackmagicRawPipelineDevice::GetOpenGLInteropHelper method
Creates an instance of a helper to get the results of a processed image as an OpenGL texture
Syntax
HRESULT GetOpenGLInteropHelper(IBlackmagicRawOpenGLInteropHelper**
interopHelper)
Parameters
interopHelper out –
Return Values
interopHelper is NULL.
IBlackmagicRawToneCurve Interface
If desired, the user application can cache these results
Related Interfaces
Method Description
Query tone curve parameters for a specific camera and gamma.

These are only currently available on Gamut: Blackmagic Design, Gamma:
Blackmagic Design Film, Blackmagic Design Extended Video,
GetToneCurve
Blackmagic Design Custom.
Note: Custom gamma can define a tone curve per clip, see
BlackmagicRawClipProcessingAttributes::GetToneCurveForCustomGamma()
EvaluateToneCurve Evaluates tone curve, returned buffer can be used to visualise curve
IBlackmagicRawToneCurve::GetToneCurve method
Query tone curve parameters for a specific camera and gamma. These are only currently available
on Gamut: Blackmagic Design, Gamma: Blackmagic Design Film, Blackmagic Design Extended
Video, Blackmagic Design Custom.
Note: Custom gamma can define a tone curve per clip, see
BlackmagicRawClipProcessingAttributes::GetToneCurveForCustomGamma()
Syntax
HRESULT GetToneCurve (
string cameraType,
string gamma,
uint16_t gen,
float* contrast,
float* saturation,
float* midpoint,
float* highlights,
float* shadows,
float* blackLevel,
float* whiteLevel,
uint16_t* videoBlackLevel)
Parameters
Type of camera, you can query this from

cameraType in
IBlackmagicRawClip::GetCameraType()
gamma in String value of gamma to use
gen in Color science gen
contrast out Contrast of tonecurve
saturation out Saturation of tonecurve
midpoint out Midpoint of tonecurve
highlights out Control the highlights in the tonecurve
shadows out Control the shadows in the tonecurve
blackLevel out Black level in the tonecurve
whiteLevel out White level in the tonecurve
videoBlackLevel out Whether there is a black level pedestal applied
Return Values
If the method succeeds, the return value is S_OK. E_POINTER is returned when any of contrast,
saturation, midpoint, highlights, shadows or videoBlackLevel are NULL. E_INVALIDARG is returned
when the provided cameraType / gamma / gen combination is invalid.
IBlackmagicRawToneCurve::EvaluateToneCurve method
Evaluates tone curve, returned buffer can be used to visualise curve
Syntax
HRESULT EvaluateToneCurve (
string cameraType,
uint16_t gen,
float contrast,
float saturation,
float midpoint,
float highlights,
float shadows,
float blackLevel,
float whiteLevel,
uint16_t videoBlackLevel,
float* array,
uint32_t arrayElementCount)
Parameters

cameraType in
gen in Color science gen
contrast in Contrast of tonecurve
saturation in Saturation of tonecurve
midpoint in Midpoint of tonecurve
highlights in Highlights of tonecurve
shadows in Shadows of tonecurve
blackLevel in Black level of tonecurve
whiteLevel in White level of tonecurve
videoBlackLevel in Do we apply a black level pedestal
array out Array to write the evaluated tonecurve in to
arrayElementCount in Size of array being provided
Return Values
If the method succeeds, the return value is S_OK. E_POINTER is returned when arrayOut is NULL.
E_INVALIDARG is returned when arrayOutElementCount is 0 or the cameraType / bmdgen
combination provided is invalid.
IBlackmagicRawConstants Interface
If desired, the user application can cache these results
Related Interfaces
IBlackmagicRaw IID_IBlackmagicRaw
Method Description
Get the clip processing attribute range for the specified

GetClipProcessingAttributeRange
attribute
Get the clip processing attribute value list for the

GetClipProcessingAttributeList
specified attribute
Get the frame processing attribute range for the

GetFrameProcessingAttributeRange
specified attribute
Get the frame processing attribute value list for the

GetFrameProcessingAttributeList
specified attribute
The ISO selection can be constrained by the analog

gain selected at record time, use this function to get a
GetISOListForAnalogGain
narrowed view of the available ISOs for a given
cameraType and analog gain values.
IBlackmagicRawConstants::GetClipProcessingAttributeRange method
Get the clip processing attribute range for the specified attribute
Syntax
HRESULT GetClipProcessingAttributeRange (
string cameraType,
BlackmagicRawClipProcessingAttribute attribute,
Variant valueMin,
Variant valueMax)
Parameters

cameraType in
attribute in Attribute to query
valueMin out Variant to store the data in
valueMax out Variant to store the data in
Return Values
If the method succeeds, the return value is S_OK. E_INVALIDARG is returned when attribute
is invalid, or the attribute does not have a range, see GetClipProcessingAttributeList().
E_POINTER is returned when valueMin or valueMax is NULL.
IBlackmagicRawConstants::GetClipProcessingAttributeList method
Get the clip processing attribute value list for the specified attribute
Syntax
HRESULT GetClipProcessingAttributeList (
string cameraType,
Variant array,
uint32_t* arrayElementCount)
Parameters

cameraType in
array out Array the results will be written to
arrayElementCount out Array element count
Return Values
is invalid, or the attribute does not have a value list, see GetClipProcessingAttributeRange().
IBlackmagicRawConstants::GetFrameProcessingAttributeRange method
Get the frame processing attribute range for the specified attribute
Syntax
HRESULT GetFrameProcessingAttributeRange (
string cameraType,
BlackmagicRawFrameProcessingAttribute
attribute,
Variant valueMin,
Variant valueMax)
Parameters

cameraType in
valueMin out Variant to store the data in
valueMax out Variant to store the data in
Return Values
is invalid, or the attribute does not have a range, see GetFrameProcessingAttributeList().
E_POINTER is returned when valueMin or valueMax is NULL.
IBlackmagicRawConstants::GetFrameProcessingAttributeList method
Get the frame processing attribute value list for the specified attribute
Syntax
HRESULT GetFrameProcessingAttributeList (
string cameraType,
Variant array,
Parameters

cameraType in
Return Values
If the method succeeds, the return value is S_OK. E_INVALIDARG is returned when attribute is
invalid, or the attribute does not have a value list, see GetFrameProcessingAttributeRange().
IBlackmagicRawConstants::GetISOListForAnalogGain method
The ISO selection can be constrained by the analog gain selected at record time, use this
function to get a narrowed view of the available ISOs for a given cameraType and analog
gain values.
Syntax
HRESULT GetISOListForAnalogGain (
string cameraType,
float analogGain,
uint16_t* array,
Parameters

cameraType in
Analog Gain, you can query this from

analogGain in ClipProcessingAttributes::GetClipAttribute
(blackmagicRawClipProcessingAttributeAnalogGain)
Return Values
If the method succeeds, the return value is S_OK. E_INVALIDARG is returned when cameraType
analogGain is invalid.
IBlackmagicRawConfiguration Interface
The configuration properties are read when the first call to OpenClip() occurs. After this
configuration properties should not be changed, and changes will be ignored.
Related Interfaces
Method Description
SetPipeline Set pipeline to use for decoding, see BlackmagicRawPipeline
GetPipeline Get pipeline used for decoding, see BlackmagicRawPipeline
Determine if a pipeline is supported by this machine. This will verify

IsPipelineSupported
relevant hardware / DLLs are installed
Sets the number of CPU threads to use while decoding. Defaults to

SetCPUThreads
number of hardware threads available on system
GetCPUThreads Gets the number of CPU threads to use while decoding
GetMaxCPUThreadCount Query the number of hardware threads available on system
SetWriteMetadataPerFrame Sets if per-frame metadata will be written to only the relevant frame.
GetWriteMetadataPerFrame Gets if the per-frame metadata will be written to only the relevant frame
Equivalent to querying the device for instruction set, pipeline, context

SetFromDevice
and command queue then calling SetInstructionSet and SetPipeline
IBlackmagicRawConfiguration::SetPipeline method
Set pipeline to use for decoding, see BlackmagicRawPipeline
Syntax
HRESULT SetPipeline (
void* pipelineContext,
void* pipelineCommandQueue)
Parameters
Set pipeline before allocating resources, as changing

pipeline in pipeline will cause the default resource manager to be
re-created
Set context to use. For CPU/CUDA/Metal/OpenCL maps

pipelineContext in
to null/CUcontext/null/cl_context
Sets commandQueue to use. For CPU/CUDA/Metal/

pipelineCommandQueue in OpenCL maps to null/CUstream/MTLCommandQueue/
cl_command_queue
Return Values
If the method succeeds, the return value is S_OK. E_FAIL is returned when the pipeline failed to
initialise.
IBlackmagicRawConfiguration::GetPipeline method
Get pipeline used for decoding, see BlackmagicRawPipeline
Syntax
HRESULT GetPipeline (
BlackmagicRawPipeline* pipeline,
void** pipelineContextOut,
void** pipelineCommandQueueOut)
Parameters
pipeline out returns the pipeline used
Returns context applied. For CPU/CUDA/Metal/OpenCL

pipelineContextOut out
maps to null/CUcontext/null/cl_context
Returns commandQueue applied. For CPU/CUDA/

pipelineCommandQueueOut out Metal/OpenCL maps to null/CUstream/
MTLCommandQueue/cl_command_queue
Return Values
IBlackmagicRawConfiguration::IsPipelineSupported method
Determine if a pipeline is supported by this machine. This will verify relevant hardware / DLLs
are installed
Syntax
HRESULT IsPipelineSupported (
Boolean* pipelineSupported)
Parameters
pipeline in Type of pipeline to query
pipelineSupported out Returned result
Return Values
If the method succeeds, the return value is S_OK. E_POINTER is returned when clip is NULL,
E_INVALIDARG is returned when pipeline is invalid
IBlackmagicRawConfiguration::SetCPUThreads method
Sets the number of CPU threads to use while decoding. Defaults to number of hardware threads
available on system
Syntax
HRESULT SetCPUThreads (uint32_t threadCount)
Parameters
Thread count to utilise, setting to 0 will default to

threadCount in
number of hardware threads available on system
Return Values
IBlackmagicRawConfiguration::GetCPUThreads method
Gets the number of CPU threads to use while decoding
Syntax
HRESULT GetCPUThreads (uint32_t* threadCount)
Parameters
threadCount out Returned thread count
Return Values
If the method succeeds, the return value is S_OK. E_POINTER is returned when threadCount is NULL.
IBlackmagicRawConfiguration::GetMaxCPUThreadCount method
Query the number of hardware threads available on system
Syntax
HRESULT GetMaxCPUThreadCount (uint32_t* threadCount)
Parameters
threadCount out Returned thread count
Return Values
maxCPUThreadCount is NULL.
IBlackmagicRawConfiguration::SetWriteMetadataPerFrame method
Sets if per-frame metadata will be written to only the relevant frame.
Syntax
HRESULT SetWriteMetadataPerFrame (Boolean writePerFrame)
Parameters
if true, frame metadata will be written to only the

writePerFrame in relevant frame, if false, setting frame metadata will set
to all frames at once
Return Values
IBlackmagicRawConfiguration::GetWriteMetadataPerFrame method
Gets if the per-frame metadata will be written to only the relevant frame
Syntax
HRESULT GetWriteMetadataPerFrame (Boolean* writePerFrame)
Parameters
if true, frame metadata will be written to only the

writePerFrame out relevant frame, if false, setting frame metadata will set
to all frames at once
Return Values
writePerFrame is NULL.
IBlackmagicRawConfiguration::SetFromDevice method
Equivalent to querying the device for instruction set, pipeline, context and command queue then calling
SetInstructionSet and SetPipeline
Syntax
HRESULT SetFromDevice(IBlackmagicRawPipelineDevice* pipelineDevice)
Parameters
pipelineDevice in –
Return Values
If the method succeeds, the return value is S_OK. E_POINTER is returned when the
pipelineDevice is NULL.
IBlackmagicRawConfigurationEx Interface
Extended Configuration for Codec Object
Related Interfaces
Method Description
GetResourceManager Get the current resource manager
Set the current resource manager, this allows the user to provide a custom
SetResourceManager
resource manager
GetInstructionSet Get the CPU instruction set used by the decoder
SetInstructionSet Set the CPU instruction set used by the decoder
IBlackmagicRawConfigurationEx::GetResourceManager method
Get the current resource manager
Syntax
HRESULT GetResourceManager (IBlackmagicRawResourceManager** resourceManager)
Parameters
resourceManager out Returned resource manager
Return Values
resourceManager is NULL.
IBlackmagicRawConfigurationEx::SetResourceManager method
Set the current resource manager, this allows the user to provide a custom resource manager
Syntax
HRESULT SetResourceManager (IBlackmagicRawResourceManager* resourceManager)
Parameters
resourceManager in setting null will restore the default resource manager
Return Values
If the method succeeds, the return value is S_OK. E_FAIL can occur when setting the a NULL
resource manager and the default resource manager failed to create.
IBlackmagicRawConfigurationEx::GetInstructionSet method
Get the CPU instruction set used by the decoder
Syntax
HRESULT GetInstructionSet (BlackmagicRawInstructionSet* instructionSet)
Parameters
instructionSet out Returned instruction set
Return Values
instructionSet is NULL.
IBlackmagicRawConfigurationEx::SetInstructionSet method
Set the CPU instruction set used by the decoder
Syntax
HRESULT SetInstructionSet (BlackmagicRawInstructionSet instructionSet)
Parameters
instructionSet in the instruction set to use
Return Values
If the method succeeds, the return value is S_OK. E_INVALIDARG is returned when instructionSet is
invalid. E_FAIL is returned when the system does not support the provided instruction set.
IBlackmagicRawResourceManager Interface
Using this interface the user can create their own Resource manager to allow ownership over
resource allocations. An internal resource manager that implements this is interface is provided
by default.
Method Description
CreateResource Called when a new resource is created
ReleaseResource Release a resource
CopyResource Copy a resource
GetResourceHostPointer Obtains a pointer to a resource's host addressable memory
IBlackmagicRawResourceManager::CreateResource method
Called when a new resource is created
Syntax
HRESULT CreateResource (
void* context,
void* commandQueue,
uint32_t sizeBytes,
BlackmagicRawResourceType type,
BlackmagicRawResourceUsage usage,
void** resource)
Parameters
context in Context on which to create the resource
commandQueue in Command Queue on which to create the resource
sizeBytes in Size (in bytes) of the resource to create
type in Type of resource to create
usage in Usage of resource to create
resource out Return the created resource
Return Values
If the method succeeds, the return value is S_OK. E_POINTER is returned when resource is NULL.
E_INVALIDARG is returned when type is invalid or does not match the current pipeline.
E_OUTOFMEMORY is returned if the allocation failed.
IBlackmagicRawResourceManager::ReleaseResource method
Release a resource
Syntax
HRESULT ReleaseResource (
void* context,
void* commandQueue,
void* resource,
BlackmagicRawResourceType type)
Parameters
context in Context the resource was created on
commandQueue in CommandQueue the resource was created on
resource in Resource to release
type in Type of resource we are releasing
Return Values
If the method succeeds, the return value is S_OK. E_INVALIDARG is returned when type is invalid or
does not match the current pipeline. E_UNEXPECTED is returned if an unexpected error occurs.
IBlackmagicRawResourceManager::CopyResource method
Copy a resource
Syntax
HRESULT CopyResource(
void* context,
void* commandQueue,
void* source,
BlackmagicRawResourceType sourceType,
void* destination,
BlackmagicRawResourceType destinationType,
uint32_t sizeBytes,
Boolean copyAsync)
Parameters
source in Source resource to copy
sourceType in Type of resource to copy from
destination in Destination resource of the copy
destinationType in Type of resource to copy to
sizeBytes in Size (in bytes) of the resource to copy
if true, queue the copy to happen asynchronously

copyAsync in
(implying the source buffer MUST exist for the duration)
Return Values
If the method succeeds, the return value is S_OK. E_INVALIDARG is returned when type is invalid or
does not match the current pipeline. E_UNEXPECTED is returned if an unexpected error occurs.
IBlackmagicRawResourceManager::GetResourceHostPointer method
Obtains a pointer to a resource’s host addressable memory
Syntax
HRESULT GetResourceHostPointer(
void* context,
void* commandQueue,
void* resource,
BlackmagicRawResourceType resourceType,
void** hostPointer)
Parameters
resource in Resource to query
resourceType in Type of resource we are querying
hostPointer out Resultant host pointer of the resource
Return Values
If the method succeeds, the return value is S_OK. E_INVALIDARG is returned when
type is invalid or does not match the current pipeline.
IBlackmagicRawMetadataIterator Interface
Iterating metadata
Method Description
Next Step to next metadata entry, will return S_FALSE when called on last entry
GetKey Query key name of this metadata entry
GetData Query data in this metadata entry
IBlackmagicRawMetadataIterator::Next method
Step to next metadata entry, will return S_FALSE when called on last entry
Syntax
HRESULT Next()
Return Values
IBlackmagicRawMetadataIterator::GetKey method
Query key name of this metadata entry
Syntax
HRESULT GetKey (string* key)
Parameters
key out Name of key
Return Values
If the method succeeds, the return value is S_OK. E_POINTER is returned when key is NULL, E_FAIL
is returned if the iterator has already stepped past the last element
IBlackmagicRawMetadataIterator::GetData method
Query data in this metadata entry
Syntax
HRESULT GetData (Variant data)
Parameters
data out Variant to store the data in
Return Values
If the method succeeds, the return value is S_OK. E_POINTER is returned when key is NULL, E_FAIL
is returned if the iterator has already stepped past the last element
IBlackmagicRawClipProcessingAttributes Interface
Clip Processing attributes allows the user to adjust clip-level processing attributes
Related Interfaces
IBlackmagicRawClip IID_IBlackmagicRawClip
Method Description
GetClipAttribute Get the attribute
SetClipAttribute Set the attribute
GetPost3DLUT Get the active 3D LUT
IBlackmagicRawClipProcessingAttributes::GetClipAttribute method
Get the attribute
Syntax
HRESULT GetClipAttribute (
Variant value)
Parameters
value out Variant to store the queried value in
Return Values
If the method succeeds, the return value is S_OK. E_INVALIDARG is returned when attribute,
E_POINTER is returned when value is NULL.
IBlackmagicRawClipProcessingAttributes::SetClipAttribute method
Set the attribute
Syntax
HRESULT SetClipAttribute (
Variant value)
Parameters
attribute in Attribute to set
value in Variant to set the value to
Return Values
If the method succeeds, the return value is S_OK. E_INVALIDARG is returned when attribute or
value is invalid. When changing the Sidecar 3D LUT parameters, it’s possible to set an attribute that
is valid but incompatible with the existing state (e.g. LUT Size = 33 when the current LUT Data is for a
17x17x17 cube). In this case, the method will return S_FALSE and temporarily disable the active
sidecar LUT until a full set of valid parameters are specified.
IBlackmagicRawClipProcessingAttributes::GetPost3DLUT method
Get the active 3D LUT
Syntax
HRESULT GetPost3DLUT (IBlackmagicRawPost3DLUT** lut)
Parameters
lut out Look up table (LUT) to query
Return Values
If the method succeeds, the return value is S_OK. E_POINTER is returned when lut is NULL.
IBlackmagicRawPost3DLUT Interface
3D Look up table (LUT) object. This object provides additional information about LUTs and gives
user the ability to control the lifetime of the resource.
Method Description
GetName Get the name of the 3D LUT
GetTitle Get the title of the 3D LUT
GetSize Get the size of the LUT. Eg, will return 17 for a 17x17x17 LUT.
GetResourceGPU Get pointer to GPU resource the LUT is stored in
GetResourceCPU Get pointer to CPU resource the LUT is stored in
GetResourceSizeBytes Get size of resource in bytes
IBlackmagicRawPost3DLUT::GetName method
Get the name of the 3D LUT
Syntax
HRESULT GetName (string* name)
Parameters
name out Returned name
Return Values
If the method succeeds, the return value is S_OK. E_POINTER is returned when name is NULL.
IBlackmagicRawPost3DLUT::GetTitle method
Get the title of the 3D LUT
Syntax
HRESULT GetTitle (string* title)
Parameters
title out Returned title
Return Values
If the method succeeds, the return value is S_OK. E_POINTER is returned when title is NULL.
IBlackmagicRawPost3DLUT::GetSize method
Get the size of the LUT. Eg, will return 17 for a 17x17x17 LUT.
Syntax
HRESULT GetSize (uint32_t* size)
Parameters
size out Returned size in pixels
Return Values
If the method succeeds, the return value is S_OK. E_POINTER is returned when size is NULL.
IBlackmagicRawPost3DLUT::GetResourceGPU method
Get pointer to GPU resource the LUT is stored in
Syntax
HRESULT GetResourceGPU (
void* context,
void* commandQueue,
BlackmagicRawResourceType* type,
void** resource)
Parameters
Context the resource should belong to. This will be API

context in
dependant, see BlackmagicRawPipeline for details
Command queue the resource should belong to. This will

commandQueue in
be API dependant, see BlackmagicRawPipeline for details
type out Returned type of resource
This will differ per API. See BlackmagicRawResourceType

resource out
for details
Return Values
If the method succeeds, the return value is S_OK. E_POINTER is returned when resource or type is
NULL. E_OUTOFMEMORY is returned when the resource is lazy created and the memory
allocation failed.
IBlackmagicRawPost3DLUT::GetResourceCPU method
Get pointer to CPU resource the LUT is stored in
Syntax
HRESULT GetResourceCPU (void** resource)
Parameters
resource out CPU resource object
Return Values
IBlackmagicRawPost3DLUT::GetResourceSizeBytes method
Get size of resource in bytes
Syntax
HRESULT GetResourceSizeBytes (uint32_t* sizeBytes)
Parameters
sizeBytes out Returned size of resource in bytes
Return Values
If the method succeeds, the return value is S_OK. E_POINTER is returned when sizeBytes is NULL.
IBlackmagicRawFrameProcessingAttributes Interface
Processing attributes which can change per frame
Related Interfaces
IBlackmagicRawFrame IID_IBlackmagicRawFrame
Method Description
GetAttribute Get the attribute
SetAttribute Set the attribute
IBlackmagicRawFrameProcessingAttributes::GetFrameAttribute method
Get the attribute
Syntax
HRESULT GetFrameAttribute (
BlackmagicRawFrameProcessingAttribute attribute,
Variant value)
Parameters
value out Variant to store the queried value in
Return Values
If the method succeeds, the return value is S_OK. E_INVALIDARG is returned when attribute,
IBlackmagicRawFrameProcessingAttributes::SetFrameAttribute method
Set the attribute
Syntax
HRESULT SetAttribute (
BlackmagicRawFrameProcessingAttribute attribute,
Variant value)
Parameters
attribute in Attribute to set
value in Variant to set the value to
Return Values
or value is invalid.
IBlackmagicRawProcessedImage Interface
This object is created by the API and provided via a ProcessComplete() callback.
Method Description
GetWidth Get the width of the processed image
GetHeight Get the height of the processed image
GetResource Get pointer to resource the image is stored in
GetResourceType Get type of resource, see BlackmagicRawResourceType
Get format of resource, see

GetResourceFormat
GetResourceSizeBytes Get size of resource in bytes
Get context and command queue that the resource was

GetResourceContextAndCommandQueue
created on
IBlackmagicRawProcessedImage::GetWidth method
Get the width of the processed image
Syntax
HRESULT GetWidth (uint32_t* width)
Parameters
width out Returned width in pixels
Return Values
If the method succeeds, the return value is S_OK. E_POINTER is returned when width is NULL.
IBlackmagicRawProcessedImage::GetHeight method
Get the height of the processed image
Syntax
HRESULT GetHeight (uint32_t* height)
Parameters
height out Returned height in pixels
Return Values
If the method succeeds, the return value is S_OK. E_POINTER is returned when height is NULL.
IBlackmagicRawProcessedImage::GetResource method
Get pointer to resource the image is stored in
Syntax
HRESULT GetResource (void** resource)
Parameters
This will differ per API.

resource out
See BlackmagicRawResourceType for details
Return Values
IBlackmagicRawProcessedImage::GetResourceType method
Get type of resource, see BlackmagicRawResourceType
Syntax
HRESULT GetResourceType (BlackmagicRawResourceType* type)
Parameters
type out Returned type of resource
Return Values
If the method succeeds, the return value is S_OK. E_POINTER is returned when type is NULL.
IBlackmagicRawProcessedImage::GetResourceFormat method
Get format of resource, see BlackmagicRawResourceFormat
Syntax
HRESULT GetResourceFormat (BlackmagicRawResourceFormat* format)
Parameters
format out Returned format of resource
Return Values
If the method succeeds, the return value is S_OK. E_POINTER is returned when format is NULL.
IBlackmagicRawProcessedImage::GetResourceSizeBytes method
Get size of resource in bytes
Syntax
HRESULT GetResourceSizeBytes (uint32_t* sizeBytes)
Parameters
sizeBytes out Returned size of resource in bytes
Return Values
If the method succeeds, the return value is S_OK. E_POINTER is returned when sizeBytes is NULL.
I BlackmagicRawProcessedImage::GetResourceContextAndCommandQueue
method
Get context and command queue that the resource was created on
Syntax
HRESULT GetResourceContextAndCommandQueue (
void** context,void** commandQueue)
Parameters
Returned context resource was created on, this native

context out
object will differ per API, see BlackmagicRawPipeline
Returned command queue resource was created on,

commandQueue out this native object will differ per API, see
BlackmagicRawPipeline
Return Values
If the method succeeds, the return value is S_OK. E_POINTER is returned when either context or
commandQueue is NULL.
IBlackmagicRawJob Interface
This is the base object that is returned when any job is created with the SDK. Use this to control and
identify jobs when callbacks occur.
Method Description
Submit the job to the decoder. This will insert the job in the decoders
internal queue. From here the relevant callback (i.e. ProcessComplete()) will
occur as soon as the job is completed.
Submit
Note: When queuing on GPU decoders, this function will not return until the
job has been submitted to the internal GPU API. So you can use GPU
synchronization methods rather than waiting for the CPU callbacks.
Abort the job. This CAN fail if the job has already been started by the
Abort
internal decoder.
SetUserData Attach some generic userdata to the job object/
GetUserData Retrieve previously attached generic userdata from the job object
IBlackmagicRawJob::Submit method
Submit the job to the decoder. This will insert the job in the decoders internal queue. From here the
relevant callback (i.e. ProcessComplete()) will occur as soon as the job is completed.
Note: When queuing on GPU decoders, this function will not return until the job has been submitted
to the internal GPU API. So you can use GPU synchronization methods rather than waiting for the
CPU callbacks.
Syntax
HRESULT Submit()
Return Values
If the method succeeds, the return value is S_OK. E_FAIL is returned if the job has already been
started. E_OUTOFMEMORY can be returned if the operation required memory and the
allocation failed.
IBlackmagicRawJob::Abort method
Abort the job. This CAN fail if the job has already been started by the internal decoder.
Syntax
HRESULT Abort()
Return Values
If the method succeeds, the return value is S_OK. E_FAIL is returned if the job has already been
aborted, or if the job cannot abort now (for example it may have been sent to GPU already)
IBlackmagicRawJob::SetUserData method
Attach some generic userdata to the job object/
Syntax
HRESULT SetUserData (void* userData)
Parameters
userData in Userdata to attach
Return Values
IBlackmagicRawJob::GetUserData method
Retrieve previously attached generic userdata from the job object
Syntax
HRESULT GetUserData (void** userData)
Parameters
userData out Userdata that was attached
Return Values
If the method succeeds, the return value is S_OK. E_POINTER is returned when userData is NULL.
IBlackmagicRawCallback Interface
Central callback object for entire codec. Jobs submitted to any clip created by this codec will have
their results provided through these function calls
Method Description
ReadComplete Called when a read has completed
DecodeComplete Called when a decode has completed
ProcessComplete Called when a process has completed
Called as a Trim job is processed to provide status

TrimProgress
updates
TrimComplete Called when a trim has completed
Called when a parse warning occured when reading a

related .sidecar file.
SidecarMetadataParseWarning Note: Parse warnings are not fatal, the offending line
will be ignored. When SaveSidecarFile() is next called,
the offending line will be removed.
Called when a parse error occured when reading a

related .sidecar file.
SidecarMetadataParseError Note: If a parse error occurs, the entire file is ignored.
When SaveSidecarFile() file is next called, the entire file
will be replaced.
PreparePipelineComplete Called when preparation of the pipeline has completed
IBlackmagicRawCallback::ReadComplete method
Called when a read has completed
Syntax
void ReadComplete (
IBlackmagicRawJob* job, HRESULT result,
IBlackmagicRawFrame* frame)
Parameters
Job created to perform the read, see

job in
CreateJobReadFrame()
result in Result of the job
frame in Frame created (will be null if the job failed
IBlackmagicRawCallback::DecodeComplete method
Called when a decode has completed
Syntax
void DecodeComplete (
IBlackmagicRawJob* job, HRESULT result)
Parameters
Job created to perform the decode, see

job in CreateJobDecode().
Note: this function is only used with manual decoders
IBlackmagicRawCallback::ProcessComplete method
Called when a process has completed
Syntax
void ProcessComplete (
IBlackmagicRawJob* job, HRESULT result,
IBlackmagicRawProcessedImage* processedImage)
Parameters
Job created to perform the process, see

job in
CreateJobDecodeAndProcess() or CreateJobProcess()
Create processed frame. This contains the final image

processedImage in
ready for display
IBlackmagicRawCallback::TrimProgress method
Called as a Trim job is processed to provide status updates
Syntax
void TrimProgress (
IBlackmagicRawJob* job, float progress)
Parameters
job in Job created to perform the trim
Progress [0, 1] which defines how the trim operation has

progress in
progressed
IBlackmagicRawCallback::TrimComplete method
Called when a trim has completed
Syntax
void TrimComplete (
IBlackmagicRawJob* job, HRESULT result)
Parameters
job in Job created to perform the trim
IBlackmagicRawCallback::SidecarMetadataParseWarning method
Called when a parse warning occured when reading a related .sidecar file.
Note: Parse warnings are not fatal, the offending line will be ignored. When SaveSidecarFile() is next
called, the offending line will be removed.
Syntax
void SidecarMetadataParseWarning (
IBlackmagicRawClip* clip,
string fileName,
uint32_t lineNumber,
string info)
Parameters
clip in Clip which was parsing the .sidecar file
fileName in Filename of the .sidecar file
lineNumber in Line number where the parse error occured
info in any additional information to the parse error
IBlackmagicRawCallback::SidecarMetadataParseError method
Called when a parse error occured when reading a related .sidecar file.
Note: If a parse error occurs, the entire file is ignored. When SaveSidecarFile() file is next called,
the entire file will be replaced.
Syntax
void SidecarMetadataParseError (
IBlackmagicRawClip* clip,
string fileName,
uint32_t lineNumber,
string info)
Parameters
clip in Clip which was parsing the .sidecar file
fileName in Filename of the .sidecar file
lineNumber in Line number where the parse error occured
info in any additional information to the parse error
IBlackmagicRawCallback::PreparePipelineComplete method
Called when preparation of the pipeline has completed
Syntax
void PreparePipelineComplete (
void* userData, HRESULT result)
Parameters
userData in Userdata specified to PreparePipeline
result in Result of the pipeline preparation
IBlackmagicRawClipAudio Interface
Interface for accessing a clips audio.
Related Interfaces
Method Description
GetAudioFormat Get format the audio was recorded in
GetAudioBitDepth Get the audio bit depth
GetAudioChannelCount Get the audio channel count
GetAudioSampleRate Get the audio sample rate
GetAudioSampleCount Get the audio sample count
GetAudioSamples Get audio samples from the clip
IBlackmagicRawClipAudio::GetAudioFormat method
Get format the audio was recorded in
Syntax
HRESULT GetAudioFormat (BlackmagicRawAudioFormat* format)
Parameters
format out Returned audio format
Return Values
If the method succeeds, the return value is S_OK. E_POINTER is returned when format is NULL.
IBlackmagicRawClipAudio::GetAudioBitDepth method
Get the audio bit depth
Syntax
HRESULT GetAudioBitDepth (uint32_t* bitDepth)
Parameters
bitDepth out Returned audio bit depth
Return Values
If the method succeeds, the return value is S_OK. E_POINTER is returned when bitDepth is NULL.
E_FAIL is returned if an error occured when reading the movie.
IBlackmagicRawClipAudio::GetAudioChannelCount method
Get the audio channel count
Syntax
HRESULT GetAudioChannelCount (uint32_t* channelCount)
Parameters
channelCount out Returned audio channel count
Return Values
If the method succeeds, the return value is S_OK. E_POINTER is returned when channelCount is
NULL. E_FAIL is returned if an error occured when reading the movie.
IBlackmagicRawClipAudio::GetAudioSampleRate method
Get the audio sample rate
Syntax
HRESULT GetAudioSampleRate (uint32_t* sampleRate)
Parameters
sampleRate out Returned audio sample rate
Return Values
If the method succeeds, the return value is S_OK. E_POINTER is returned when sampleRate
is NULL, E_FAIL is returned if an error occured when reading the movie.
IBlackmagicRawClipAudio::GetAudioSampleCount method
Get the audio sample count
Syntax
HRESULT GetAudioSampleCount (uint64_t* sampleCount)
Parameters
sampleCount out Returned audio sample count
Return Values
If the method succeeds, the return value is S_OK. E_POINTER is returned when sampleCount
is NULL, E_FAIL is returned if an error occured when reading the movie.
IBlackmagicRawClipAudio::GetAudioSamples method
Get audio samples from the clip
Syntax
HRESULT GetAudioSamples (
int64_t sampleFrameIndex,
void* buffer,
uint32_t bufferSizeBytes,
uint32_t maxSampleCount,
uint32_t* samplesRead,
uint32_t* bytesRead)
Parameters
sampleFrameIndex in Sample frame index to start reading from
buffer in Buffer to write the sample data in to
bufferSizeBytes in Size of the provided buffer in bytes
maxSampleCount in Max sample count to get with this query
samplesRead out Returned read sample count
bytesRead out Returned read byte count
Return Values
If the method succeeds, the return value is S_OK. E_POINTER is returned when bufferOut is NULL,
IBlackmagicRawFrame Interface
A frame that has been read but not yet processed. This is returned in the ReadComplete() callback.
From here the user should prepare the frame for processing, and call DecodeAndProcessFrame().
QueryInterface can return: 1. This frames FrameProcessingAttributes, modify this to change
processing attributes of this frame in the clip. 2. FrameEx
Related Interfaces
IBlackmagicRawFrameEx IID_IBlackmagicRawFrameEx
IBlackmagicRawFrameProcessingAttributes IID_IBlackmagicRawFrameProcessingAttributes
Method Description
GetFrameIndex Get the frameIndex
GetTimecode Get a formatted timecode for this frame
Create a medatadata iterator to iterate through the

GetMetadataIterator
metadata in this frame
GetMetadata Query a single frame metadata value defined by key
Set metadata to this frame, this data is not saved to disk

SetMetadata
until IBlackmagicRawClip::SaveSidecar() is called.
Clone this frame’s FrameProcessingAttributes into another

copy. From here the returned FrameProcessingAttributes
can be modified, and then provided to DecodeAndProcess()
CloneFrameProcessingAttributes allowing the user to decode the frame with different
processing attributes than specified in the clip. This is
useful when the user wishes to preview different processing
attributes.
Set the resolution scale we want to decode this image to.

SetResolutionScale This can be used to enhance turn-around time when
working on the project
GetResolutionScale Get the resolution scale set to the frame
Set the desired resource format that we want to processing

SetResourceFormat
this frame in to
GetResourceFormat Get the resource format this frame will be processed in to
Create a job that will decode and process our image. When
CreateJobDecodeAndProcessFrame
completed we will receive a ProcessComplete() callback
IBlackmagicRawFrame::GetFrameIndex method
Get the frameIndex
Syntax
HRESULT GetFrameIndex (uint64_t* frameIndex)
Parameters
frameIndex out Returned frame index
Return Values
If the method succeeds, the return value is S_OK. E_POINTER is returned when frameIndex is NULL.
IBlackmagicRawFrame::GetTimecode method
Get a formatted timecode for this frame
Syntax
HRESULT GetTimecode (string* timecode)
Parameters
timecode out Returned timecode for this frame
Return Values
If the method succeeds, the return value is S_OK. E_POINTER is returned when timecode is NULL.
E_UNEXPECTED is returned if an unexpected error occurs.
IBlackmagicRawFrame::GetMetadataIterator method
Create a medatadata iterator to iterate through the metadata in this frame
Syntax
HRESULT GetMetadataIterator (IBlackmagicRawMetadataIterator** iterator)
Parameters
iterator out Returned metadata object
Return Values
If the method succeeds, the return value is S_OK. E_POINTER is returned when iterator is NULL.
E_FAIL can occur if the iterator failed to create.
IBlackmagicRawFrame::GetMetadata method
Query a single frame metadata value defined by key
Syntax
HRESULT GetMetadata (
string key, Variant value)
Parameters
key in Key of the frame metadata entry we are looking for
Returned value of frame metadata entry at the

value out
provided key
Return Values
If the method succeeds, the return value is S_OK. E_INVALIDARG is returned when key is invalid.
IBlackmagicRawFrame::SetMetadata method
Set metadata to this frame, this data is not saved to disk until
IBlackmagicRawClip::SaveSidecar() is called.
Syntax
HRESULT SetMetadata (
string key, Variant value)
Parameters
Key of the frame metadata entry we want to set.

key in Note: to clear metadata from the sidecar and restore
what was originally in the movie, set value to NULL.
value in Value we want to set to the frame metadata entry
Return Values
If the method succeeds, the return value is S_OK. E_INVALIDARG is returned when key is invalid
or value is of incorrect type. E_FAIL is returned if the metadata failed to write.
IBlackmagicRawFrame::CloneFrameProcessingAttributes method
Clone this frame’s FrameProcessingAttributes into another copy. From here the returned
FrameProcessingAttributes can be modified, and then provided to DecodeAndProcess() allowing
the user to decode the frame with different processing attributes than specified in the clip. This is
useful when the user wishes to preview different processing attributes.
Syntax
HRESULT CloneFrameProcessingAttributes (
IBlackmagicRawFrameProcessingAttributes**
frameProcessingAttributes)
Parameters
frameProcessingAttributes out Returned created FrameProcessingAttributes object
Return Values
frameProcessingAttributes is NULL. E_FAIL can occur if the object failed to create.
IBlackmagicRawFrame::SetResolutionScale method
Set the resolution scale we want to decode this image to. This can be used to enchance turn-around
time when working on the project
Syntax
HRESULT SetResolutionScale (BlackmagicRawResolutionScale resolutionScale)
Parameters
resolutionScale in Desired resolution scale
Return Values
If the method succeeds, the return value is S_OK. E_INVALIDARG is returned when gamut is invalid.
IBlackmagicRawFrame::GetResolutionScale method
Get the resolution scale set to the frame
Syntax
HRESULT GetResolutionScale (BlackmagicRawResolutionScale* resolutionScale)
Parameters
resolutionScale out Returned resolution scale
Return Values
resolutionScale is NULL.
IBlackmagicRawFrame::SetResourceFormat method
Set the desired resource format that we want to processing this frame in to
Syntax
HRESULT SetResourceFormat (BlackmagicRawResourceFormat resourceFormat)
Parameters
The desired resource format, see

resourceFormat in
Return Values
If the method succeeds, the return value is S_OK. E_INVALIDARG is returned when resourceFormat
is invalid.
IBlackmagicRawFrame::GetResourceFormat method
Get the resource format this frame will be processed in to
Syntax
HRESULT GetResourceFormat (BlackmagicRawResourceFormat* resourceFormat)
Parameters
Returned resource format, see

resourceFormat out
Return Values
resourceFormat is NULL.
IBlackmagicRawFrame::CreateJobDecodeAndProcessFrame method
Create a job that will decode and process our image. When completed we will receive
a ProcessComplete() callback
Syntax
HRESULT CreateJobDecodeAndProcessFrame (
IBlackmagicRawClipProcessingAttributes*
clipProcessingAttributes,
IBlackmagicRawFrameProcessingAttributes*
frameProcessingAttributes,
IBlackmagicRawJob** job)
Parameters
This allows the user to provide custom clip processing

attributes which are not set to the clip. This allows the
clipProcessingAttributes in
user to preview how the image would look with different
settings before applying them to the clip
This allows the user to provide custom frame

processing attributes which are not set to the frame.
frameProcessingAttributes in This allows the user to preview how the image would
look with different settings before applying them to the
frame
Created job object used to track the job.

job out
Note: Be sure to call Submit() on the job when ready
Return Values
If the method succeeds, the return value is S_OK. E_POINTER is returned when job is NULL. E_
INVALIDARG is returned if SetCallback() hasn’t been called on the related BlackmagicRaw object.
E_FAIL can occur if the decoder failed to start or the job failed to create.
IBlackmagicRawFrameEx Interface
Query additional information for the frame. This information is useful when decoding via the
manual decoders.
Related Interfaces
IBlackmagicRawFrame IID_IBlackmagicRawFrame
Method Description
Get the frames bistream size in bytes we’ve read off

GetBitStreamSizeBytes
disk.
Query what the resolution of the processed image will

GetProcessedImageResolution be given the input resolution and the ResolutionScale
applied
IBlackmagicRawFrameEx::GetBitStreamSizeBytes method
Get the frames bistream size in bytes we’ve read off disk.
Syntax
HRESULT GetBitStreamSizeBytes (uint32_t* bitStreamSizeBytes)
Parameters
bitStreamSizeBytes out Returned bitstream size in bytes
Return Values
bitStreamSizeBytes is NULL.
IBlackmagicRawFrameEx::GetProcessedImageResolution method
Query what the resolution of the processed image will be given the input resolution and the
ResolutionScale applied
Syntax
HRESULT GetProcessedImageResolution (
uint32_t* width,
uint32_t* height)
Parameters
width out The resultant calculated width of the processed image
height out The resultant calculated height of the processed image
Return Values
If the method succeeds, the return value is S_OK. E_POINTER is returned when width or
height is NULL.
IBlackmagicRawManualDecoderFlow1 Interface
Manual decoders give you more control over which buffers are used and how things are queued.
IBlackmagicRawManualDecoderFlow1 is a pure-CPU solution.
Note: these decoders are optional and targetted at advanced users
Related Interfaces
Method Description
The manual decoders work with data blobs rather than

API objects. This allows the user to transfer the data
blob to another codec instance or potentially another
PopulateFrameStateBuffer
computer for processing. This function converts the
internal state of IBlackmagicRawFrame to frame state
buffer, which is used to perform the decode
GetFrameStateSizeBytes Query the same of the FrameState buffer in bytes
GetDecodedSizeBytes Query the size of the decoded buffer
GetProcessedSizeBytes Query the size of the processed buffer
GetPost3DLUTSizeBytes Query the size of the post 3D LUT buffer
Create a job to decode a frame. After this decode is

complete the decoded buffer will need to be processed
CreateJobDecode to get final result.
This decode completion will be notified via the
OnDecodeComplete() callback
Create a job to process a frame. After this process is

CreateJobProcess complete a final processed image will be provided via a
OnProcessComplete() callback
IBlackmagicRawManualDecoderFlow1::PopulateFrameStateBuffer method
The manual decoders work with data blobs rather than API objects. This allows the user to transfer
the data blob to another codec instance or potentially another computer for processing. This
function converts the internal state of IBlackmagicRawFrame to frame state buffer, which is used to
perform the decode
Syntax
HRESULT PopulateFrameStateBuffer (
IBlackmagicRawFrame* frame,
void* frameState,
uint32_t frameStateSizeBytes)
Parameters
frame in Frame to read when creating a frame state
optionally provide custom clip processing attributes to

use, rather than values inside clip
optionally provide custom frame processing attributes

frameProcessingAttributes in
to use, rather than using values inside frame
frameState out output buffer location to store framebuffer information
frameStateSizeBytes in size (in bytes) of output framebuffer location
Return Values
If the method succeeds, the return value is S_OK. E_POINTER is returned when frameState is
NULL. E_INVALIDARG is returned when frame is NULL or frameStateBufferSizeBytes is too small.
IBlackmagicRawManualDecoderFlow1::GetFrameStateSizeBytes method
Query the same of the FrameState buffer in bytes
Syntax
HRESULT GetFrameStateSizeBytes (uint32_t* frameStateSizeBytes)
Parameters
frameStateSizeBytes out Returns the size in bytes
Return Values
frameStateSizeBytes is NULL.
IBlackmagicRawManualDecoderFlow1::GetDecodedSizeBytes method
Query the size of the decoded buffer
Syntax
HRESULT GetDecodedSizeBytes (
void* frameStateBufferCPU,
uint32_t* decodedSizeBytes)
Parameters
frameStateBufferCPU in Previously prepared frame state buffer
decodedSizeBytes out Returns size of decoded frame in bytes
Return Values
If the method succeeds, the return value is S_OK. E_POINTER is returned when decodedSizeBytes
is NULL. E_INVALIDARG is returned when frameStateBufferCPU is invalid
IBlackmagicRawManualDecoderFlow1::GetProcessedSizeBytes method
Query the size of the processed buffer
Syntax
HRESULT GetProcessedSizeBytes (
uint32_t* processedSizeBytes)
Parameters
processedSizeBytes out Returns size of processed frame in bytes
Return Values
processedSizeBytes is NULL. E_INVALIDARG is returned when frameStateBufferCPU is invalid
IBlackmagicRawManualDecoderFlow1::GetPost3DLUTSizeBytes method
Query the size of the post 3D LUT buffer
Syntax
HRESULT GetPost3DLUTSizeBytes (
uint32_t* post3DLUTSizeBytes)
Parameters
StateBufferCPU in Previously prepared frame state buffer
post3DLUTSizeBytes out Returns size of post 3D LUT buffer in bytes
Return Values
IBlackmagicRawManualDecoderFlow1::CreateJobDecode method
Create a job to decode a frame. After this decode is complete the decoded buffer will need to be
processed to get final result. This decode completion will be notified via the
Syntax
HRESULT CreateJobDecode (
void* frameStateBufferCPU, void* bitStreamBufferCPU,
void* decodedBufferCPU, IBlackmagicRawJob** job)
Parameters
Previously read bitstream buffer, see

bitStreamBufferCPU in
BlackmagicRawClipEx::CreateJobReadFrame()
decodedBufferCPU in Buffer to store decoded frame in
Job created to perform the decode.

job out Note: Remember to call job->Submit() to submit the job
to the decoder!
Return Values
If the method succeeds, the return value is S_OK. E_POINTER is returned when job is NULL.
E_INVALIDARG is returned if frameStateBufferCPU, bitStreamBufferCPU or decodedBufferCPU is
invalid. E_INVALIDARG can also be returned if SetCallback() hasn’t been called on the related
BlackmagicRaw object. E_FAIL can occur if the decoder failed to start or the job failed to create.
IBlackmagicRawManualDecoderFlow1::CreateJobProcess method
Create a job to process a frame. After this process is complete a final processed image will
be provided via a OnProcessComplete() callback
Syntax
HRESULT CreateJobProcess (
void* frameStateBufferCPU, void* decodedBufferCPU,
void* processedBufferCPU, IBlackmagicRawJob** job)
Parameters
decodedBufferCPU in Previously decoded buffer to read from
processedBufferCPU in Buffer to store processed image in
Post3D LUT buffer to apply, should be non-null when

post3DLUTBufferCPU in
frameState requires it
Job created to perform the process.

to the decoder
Return Values
E_INVALIDARG is returned if frameStateBufferCPU, decodedBufferCPU or processedBufferCPU is
IBlackmagicRawManualDecoderFlow2 Interface
Manual decoders give you more control over which buffers are used and how things are queued.
IBlackmagicRawManualDecoderFlow2 is a hybrid CPU/GPU solution. This will likely be faster than
Flow1, however it will depend on the GPU in the users system.
Note: These decoders are optional and targetted at advanced users
Related Interfaces
Method Description
The manual decoders work with data blobs rather than

API objects. This allows the user to transfer the data
blob to another codec instance or potentially another
PopulateFrameStateBuffer
computer for processing. This function converts the
internal state of IBlackmagicRawFrame to frame state
buffer, which is used to perform the decode
GetFrameStateSizeBytes Query the same of the FrameState buffer in bytes
GetDecodedSizeBytes Query the size of the decoded buffer
GetWorkingSizeBytes Query the size of the working buffer
GetProcessedSizeBytes Query the size of the processed buffer
GetPost3DLUTSizeBytes Query the size of the post 3D LUT buffer
Create a job to decode a frame. This is performed on

CPU. After this decode is complete the decoded buffer
CreateJobDecode will need to be processed to get final result. This
decode completion will be notified via the
Create a job to process a frame. This is performed on

the specified GPU. After this process is complete a final
CreateJobProcess
processed image will be provided via a
OnProcessComplete() callback
IBlackmagicRawManualDecoderFlow2::PopulateFrameStateBuffer method
The manual decoders work with data blobs rather than API objects. This allows the user to transfer
the data blob to another codec instance or potentially another computer for processing. This
function converts the internal state of IBlackmagicRawFrame to frame state buffer, which is used to
perform the decode
Syntax
HRESULT PopulateFrameStateBuffer
(IBlackmagicRawFrame* frame,
void* frameState,
uint32_t frameStateSizeBytes)
Parameters
frame in Frame to read when creating a frame state
optionally provide custom clip processing attributes to

use, rather than values inside clip
optionally provide custom frame processing attributes

to use, rather than using values inside frame
frameState out output buffer location to store framebuffer information
frameStateSizeBytes in size (in bytes) of output framebuffer location
Return Values
If the method succeeds, the return value is S_OK. E_POINTER is returned when frameState is NULL.
E_INVALIDARG is returned when frame is NULL or frameStateBufferSizeBytes is too small.
IBlackmagicRawManualDecoderFlow2::GetFrameStateSizeBytes method
Query the same of the FrameState buffer in bytes
Syntax
HRESULT GetFrameStateSizeBytes (uint32_t* frameStateSizeBytes)
Parameters
frameStateSizeBytes out Returns the size in bytes
Return Values
frameStateSizeBytes is NULL.
IBlackmagicRawManualDecoderFlow2::GetDecodedSizeBytes method
Query the size of the decoded buffer
Syntax
HRESULT GetDecodedSizeBytes
(void* frameStateBufferCPU, uint32_t* decodedSizeBytes)
Parameters
decodedSizeBytes out Returns size of decoded frame in bytes
Return Values
If the method succeeds, the return value is S_OK. E_POINTER is returned when decodedSizeBytes
is NULL. E_INVALIDARG is returned when frameStateBufferCPU is invalid
IBlackmagicRawManualDecoderFlow2::GetWorkingSizeBytes method
Query the size of the working buffer
Syntax
HRESULT GetWorkingSizeBytes (
void* frameStateBufferCPU, uint32_t* workingSizeBytes)
Parameters
workingSizeBytes out Returns size of working buffer in bytes
Return Values
If the method succeeds, the return value is S_OK. E_POINTER is returned when workingSizeBytes is
NULL. E_INVALIDARG is returned when frameStateBufferCPU is invalid
IBlackmagicRawManualDecoderFlow2::GetProcessedSizeBytes method
Query the size of the processed buffer
Syntax
HRESULT GetProcessedSizeBytes (
uint32_t* processedSizeBytes)
Parameters
processedSizeBytes out Returns size of the processed buffer in bytes
Return Values
IBlackmagicRawManualDecoderFlow2::GetPost3DLUTSizeBytes method
Query the size of the post 3D LUT buffer
Syntax
HRESULT GetPost3DLUTSizeBytes (
void* frameStateBufferCPU,uint32_t* post3DLUTSizeBytes)
Parameters
post3DLUTSizeBytes out Returns size of post 3D LUT buffer in bytes
Return Values
IBlackmagicRawManualDecoderFlow2::CreateJobDecode method
Create a job to decode a frame. This is performed on CPU. After this decode is complete the
decoded buffer will need to be processed to get final result. This decode completion will be notified
via the OnDecodeComplete() callback
Syntax
HRESULT CreateJobDecode (
void* bitStreamBufferCPU,
void* decodedBufferCPU,
Parameters
Query the size of the processed buffer.

frameStateBufferCPU in Note: this is a CPU resource (and thus stored in CPU
memory)
Previously read bitream buffer, see

BlackmagicRawClipEx::CreateJobReadFrame().
bitStreamBufferCPU in
Note: this is a CPU resource (and thus stored in CPU
memory)
CPU resource where we the decoded buffer will be

written to.
decodedBufferCPU in
Note: this is a CPU resource (and thus stored in CPU
memory)
Job created to perform the decode.

to the decoder!
Return Values
E_INVALIDARG is returned if frameStateBufferCPU, bitStreamBufferCPU or decodedBufferCPU is
IBlackmagicRawManualDecoderFlow2::CreateJobProcess method
Create a job to process a frame. This is performed on the specified GPU. After this process is
complete a final processed image will be provided via a OnProcessComplete() callback
Syntax
HRESULT CreateJobProcess (
void* context,
void* commandQueue,
void* decodedBufferGPU,
void* workingBufferGPU,
void* processedBufferGPU,
Parameters
Context to perform the process on. This will be API

context in
dependant, see BlackmagicRawPipeline for details
Command queue to perform the process on. This will be

commandQueue in
API dependant, see BlackmagicRawPipeline for details
Previously prepared frame state buffer.

frameStateBufferCPU in Note: this is a CPU resource (and thus stored in CPU
memory)
GPU resource where the decoded buffer has been

decoded in to.
Note: this is a GPU resource, and its type will differ
decodedBufferGPU in
depending on API, see BlackmagicRawResourceType.
Note: The users responsibility to transfer the decoded
buffer from CPU to GPU before calling this function.
workingBufferGPU in An additional GPU resource uses as working memory
Resource to store the processed buffer in to.

processedBufferGPU in Note: this is a GPU resource, and thus it's type will be
API dependant, see BlackmagicRawPipeline for details
Post3D LUT buffer to apply, should be non-null when

post3DLUTBufferGPU in
frameState requires it
Job created to perform the process.

to the decoder
Return Values
E_INVALIDARG is returned if context, commandQueue, frameStateBufferCPU, decodedBufferGPU,
workingBufferGPU or processedBufferGPU is invalid. E_INVALIDARG can also be returned if
SetCallback() hasn’t been called on the related BlackmagicRaw object. E_FAIL can occur if the
decoder failed to start or the job failed to create.
IBlackmagicRawClip Interface
Clip object, created by calling IBlackmagicRaw::OpenClip()
Related Interfaces
IBlackmagicRawClipEx IID_IBlackmagicRawClipEx
IBlackmagicRawClipAudio IID_IBlackmagicRawClipAudio
IBlackmagicRawClipProcessingAttributes IID_IBlackmagicRawClipProcessingAttributes
Method Description
GetWidth Get the width of the clip
GetHeight Get the height of the clip
GetFrameRate Get the frame rate of the clip
GetFrameCount Get the frame count in the clip
GetTimecodeForFrame Get the timecode for the specified frame
GetMetadataIterator Create a medatadata iterator to iterate through the metadata in this clip
GetMetadata Query a single clip metadata value defined by key
Set metadata to this clip, this data is not saved to disk until
SetMetadata
IBlackmagicRawClip::SaveSidecar() is called
Get the camera type that this clip was

GetCameraType
recorded on
Clone this clip’s ClipProcessingAttributes into another copy. From here

the returned ClipProcessingAttributes can be modified, and then
CloneClipProcessingAttributes provided to DecodeAndProcess() allowing the user to decode the frame
with different processing attributes than specified in the clip. This is
useful when the user wishes to preview different processing attributes.
GetMulticardFileCount Queries how many cards this movie was originally recorded on to
Queries if a particular card file from the original recording are present. If
IsMulticardFilePresent
files are missing the movie will still play back, just at a lower framerate
GetSidecarFileAttached Returns if a relevant .sidecar file was present on disk
This will save all set metadata and processing attributes to the .sidecar
SaveSidecarFile file on disk. From here the clip can be safely closed and data will be
preserved
Reload the .sidecar file, this will replace all previously non-saved
ReloadSidecarFile
metadata and processing attributes with the contents of the .sidecar file
Create a job that will read the frames bitstream into memory. When
CreateJobReadFrame
completed we will receive a ReadComplete() callback
A trim will export part of the clip with the .sidecar file baked in to a new
CreateJobTrim .braw file. This is an asynchronous job and can take some time
depending on the length of the trim
IBlackmagicRawClip::GetWidth method
Get the width of the clip
Syntax
HRESULT GetWidth (uint32_t* width)
Parameters
width out Returns the width of the clip, in pixels
Return Values
If the method succeeds, the return value is S_OK. E_POINTER is returned when width is NULL.
IBlackmagicRawClip::GetHeight method
Get the height of the clip
Syntax
HRESULT GetHeight (uint32_t* height)
Parameters
height out Returns the height of the clip, in pixels
Return Values
If the method succeeds, the return value is S_OK. E_POINTER is returned when height is NULL.
IBlackmagicRawClip::GetFrameRate method
Get the frame rate of the clip
Syntax
HRESULT GetFrameRate (float* frameRate)
Parameters
frameRate out Returns the frame rate of the clip, in frames per second
Return Values
If the method succeeds, the return value is S_OK. E_POINTER is returned when frameRate is NULL.
IBlackmagicRawClip::GetFrameCount method
Get the frame count in the clip
Syntax
HRESULT GetFrameCount (uint64_t* frameCount)
Parameters
frameCount out Returns the number of frames in the clip
Return Values
If the method succeeds, the return value is S_OK. E_POINTER is returned when frameCount is NULL.
IBlackmagicRawClip::GetTimecodeForFrame method
Get the timecode for the specified frame
Syntax
HRESULT GetTimecodeForFrame
(uint64_t frameIndex, string* timecode)
Parameters
frameIndex in Index of the frame we are querying
timecode out Returns a formatted timecode for the specified frame
Return Values
If the method succeeds, the return value is S_OK. E_INVALIDARG is returned when frameIndex is
out of range. E_POINTER is returned when timecode is NULL.
IBlackmagicRawClip::GetMetadataIterator method
Create a medatadata iterator to iterate through the metadata in this clip
Syntax
HRESULT GetMetadataIterator (IBlackmagicRawMetadataIterator** iterator)
Parameters
iterator out Returned metadata object
Return Values
If the method succeeds, the return value is S_OK. E_POINTER is returned when iterator is NULL.
E_FAIL can occur if the iterator failed to create.
IBlackmagicRawClip::GetMetadata method
Query a single clip metadata value defined by key
Syntax
HRESULT GetMetadata
(string key, Variant value)
Parameters
key in Key of the clip metadata entry we are looking for
value out Returned value of clip metadata entry at the provided key
Return Values
If the method succeeds, the return value is S_OK. E_INVALIDARG is returned when key is invalid.
IBlackmagicRawClip::SetMetadata method
Set metadata to this clip, this data is not saved to disk until
IBlackmagicRawClip::SaveSidecar() is called
Syntax
HRESULT SetMetadata
(string key, Variant value)
Parameters
Key of the clip metadata entry we want to set.

key in Note: to clear metadata from the sidecar and restore
what was originally in the movie, set value to NULL.
value in Value we want to set to the clip metadata entry
Return Values
If the method succeeds, the return value is S_OK. E_INVALIDARG is returned when key is invalid or
value is of incorrect type. E_FAIL is returned if the metadata failed to write.
IBlackmagicRawClip::GetCameraType method
Get the camera type that this clip was recorded on
Syntax
HRESULT GetCameraType (string* cameraType)
Parameters
Returned camera type. This string can be used for

cameraType out display purposes and/or query properties though
IBlackmagicRawConstants
Return Values
cameraType is NULL.
IBlackmagicRawClip::CloneClipProcessingAttributes method
Clone this clip’s ClipProcessingAttributes into another copy. From here the returned
ClipProcessingAttributes can be modified, and then provided to DecodeAndProcess() allowing the
user to decode the frame with different processing attributes than specified in the clip. This is useful
when the user wishes to preview different processing attributes.
Syntax
HRESULT CloneClipProcessingAttributes
(IBlackmagicRawClipProcessingAttributes** clipProcessingAttributes)
Parameters
clipProcessingAttributes out Returned created ClipProcessingAttributes object
Return Values
clipProcessingAttributes is NULL. E_FAIL can occur if the object failed to create.
IBlackmagicRawClip::GetMulticardFileCount method
Queries how many cards this movie was originally recorded on to
Syntax
HRESULT GetMulticardFileCount (uint32_t* multicardFileCount)
Parameters
multicardFileCount out Returned multicard file count
Return Values
multicardFileCount is NULL.
IBlackmagicRawClip::IsMulticardFilePresent method
Queries if a particular card file from the original recording are present. If files are missing the movie
will still play back, just at a lower framerate
Syntax
HRESULT IsMulticardFilePresent (
uint32_t index,
Boolean* isMulticardFilePresent)
Parameters
index in Frame index to query
isMulticardFilePresent out Returned boolean indicating if this file was present
Return Values
isMulticardFilePresent is NULL.
IBlackmagicRawClip::GetSidecarFileAttached method
Returns if a relevant .sidecar file was present on disk
Syntax
HRESULT GetSidecarFileAttached (Boolean* isSidecarFileAttached)
Parameters
Returned boolean indicating if the .sidecar file was

isSidecarFileAttached out
present on disk
Return Values
isSidecarFileAttached is NULL.
IBlackmagicRawClip::SaveSidecarFile method
This will save all set metadata and processing attributes to the .sidecar file on disk. From here the
clip can be safely closed and data will be preserved
Syntax
HRESULT SaveSidecarFile()
Return Values
If the method succeeds, the return value is S_OK. E_FAIL is returned if the save operation failed.
IBlackmagicRawClip::ReloadSidecarFile method
Reload the .sidecar file, this will replace all previously non-saved metadata and processing attributes
with the contents of the .sidecar file
Syntax
HRESULT ReloadSidecarFile()
Return Values
If the method succeeds, the return value is S_OK. E_FAIL is returned if the load operation failed.
IBlackmagicRawClip::CreateJobReadFrame method
Create a job that will read the frames bitstream into memory. When completed we will receive
a ReadComplete() callback
Syntax
HRESULT CreateJobReadFrame (
uint64_t frameIndex, IBlackmagicRawJob** job)
Parameters
frameIndex in The frame index to read

job out
Return Values
E_INVALIDARG is returned if frameIndex is out of range or SetCallback() hasn’t been called on the
related BlackmagicRaw object. E_FAIL can occur if the job failed to create.
IBlackmagicRawClip::CreateJobTrim method
A trim will export part of the clip with the .sidecar file baked in to a new .braw file. This is an
asynchronous job and can take some time depending on the length of the trim
Syntax
HRESULT CreateJobTrim (
string fileName,
uint64_t frameIndex,
uint64_t frameCount,
Parameters
fileName in Target file name where to write the trimmed movie
frameIndex in The frame index to start trimming at
frameCount in The number of frames we want to trim
clipProcessingAttributes in Processing attributes to be applied to the trimmed clip
Processing attributes to be applied to each frame of the

trimmed clip

job out
Return Values
If the method succeeds, the return value is S_OK. E_POINTER is returned when job is NULL. E_
INVALIDARG is returned if SetCallback() hasn’t been called on the related BlackmagicRaw object.
E_FAIL can occur if the job failed to create.
IBlackmagicRawClipEx Interface
Extended use of IBlackmagicRawClip, to pass custom bitstream
Related Interfaces
Method Description
Inspects all frames in the movie and will return the

GetMaxBitStreamSizeBytes
maximum bit stream size encountered.
GetBitStreamSizeBytes Returns the bitsream size for the provided frame
Create a job that will read the frames bitstream into

memory. When completed we will receive a
CreateJobReadFrame ReadComplete() callback. This extended variation
allows the user to control exactly where the bistream is
stored in memory.
Queries the timecode info for the clip. This information

can be used to externally calculate valid timecodes
QueryTimecodeInfo from a frameIndex. Alternatively you can call
IBlackmagicRawFrame::GetTimecode() on a frame
object
IBlackmagicRawClipEx::GetMaxBitStreamSizeBytes method
Inspects all frames in the movie and will return the maximum bit stream size encountered.
Syntax
HRESULT GetMaxBitStreamSizeBytes (uint32_t* maxBitStreamSizeBytes)
Parameters
The maximum bit stream size in bytes, for any frame in

maxBitStreamSizeBytes out
the clip
Return Values
maxBitStreamSizeBytes is NULL.
IBlackmagicRawClipEx::GetBitStreamSizeBytes method
Returns the bitsream size for the provided frame
Syntax
HRESULT GetBitStreamSizeBytes (
uint32_t* bitStreamSizeBytes)
Parameters
frameIndex in The frame index to query
bitStreamSizeBytes out Returned maximum bitstream size found in bytes.
Return Values
If the method succeeds, the return value is S_OK. E_POINTER is returned when bitStreamSizeBytes
is NULL. E_INVALIDARG is returned when frameIndex is invalid. E_FAIL is returned if an error
occured when reading the movie.
IBlackmagicRawClipEx::CreateJobReadFrame method
Create a job that will read the frames bitstream into memory. When completed we will receive
a ReadComplete() callback. This extended variation allows the user to control exactly where
the bistream is stored in memory.
Syntax
HRESULT CreateJobReadFrame (
void* bitStream,
uint32_t bitStreamSizeBytes,
Parameters
frameIndex in The frame index to read
output CPU resource (i.e. memory address) where the

bitStream out
frame’s bitstream data is written to.
size of the bitstream buffer (in bytes) the frame data is

bitStreamSizeBytes in
being written to.

job out
Return Values
If the method succeeds, the return value is S_OK. E_POINTER is returned when bitStream or job is
NULL. E_INVALIDARG is returned if frameIndex is out of range or bitStreamSizeBytes is 0.
E_INVALIDARG is also returned if SetCallback() hasn’t been called on the related BlackmagicRaw
object. E_FAIL can occur if the job failed to create.
IBlackmagicRawClipEx::QueryTimecodeInfo method
Queries the timecode info for the clip. This information can be used to externally calculate valid
timecodes from a frameIndex. Alternatively you can call IBlackmagicRawFrame::GetTimecode() on a
frame object
Syntax
HRESULT QueryTimecodeInfo (
uint32_t* baseFrameIndex,
Boolean* isDropFrameTimecode)
Parameters
Frame index (at the clips framerate) where the timecode

baseFrameIndex out
begins.
Returns whether this movie has a drop frame timecode

isDropFrameTimecode out
or not.
Return Values
If the method succeeds, the return value is S_OK. E_POINTER is returned when baseFrameIndex or
isDropFrameTimecode is NULL. E_FAIL is returned if an error occured when reading the movie.

Blackmagic RAW SDK

Uploaded by

Document Informationclick to expand document information

Copyright:

Available Formats

Blackmagic RAW SDK

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Blackmagic RAW SDK

Uploaded by

Copyright:

Available Formats

Developer Information

Blackmagic RAW API

DECODER .Braw .Sidecar

METAL CUDA OPENCL

1.1 Decoder Overview

Introduction and Overview 8

Introduction and Overview 9

2.2 Clip Object

Introduction and Overview 10

3.0 SDK Operations and flow

IBlackmagicRawClip IBlackmagicRawFrame IBlackmagicRawProcessedImage

3.1 Manual Decoders

Please see the IBlackmagicRawManualDecoder* interfaces available in the API header to

4.0 GPU Configuration

Introduction and Overview 11

The pipeline iterator is created via IBlackmagicRawFactory’s CreatePipelineIterator method.

4.2 Pipeline device iterators

4.3 Pipeline preparation

A pipeline is prepared on IBlackmagicRaw with either PreparePipeline (providing context and

4.4 Multi GPU Devices

Introduction and Overview 12

Default: Full Res.

Options: – Full Res.

Color Science Version

Default: Read from metadata

Options: Use IBlackmagicRawConstants::GetClipProcessingAttributeList()

Default: Read from metadata

Options: Use IBlackmagicRawConstants::GetClipProcessingAttributeList()

Default: Read from metadata.

Options: Use IBlackmagicRawConstants::GetClipProcessingAttributeList()

Default: Read from metadata.

Options: Use IBlackmagicRawConstants::GetFrameProcessingAttributeRange()

Range: Use IBlackmagicRawConstants::GetFrameProcessingAttributeRange()

Recommended UI Controls and Behavior 13

Range: Use IBlackmagicRawConstants::GetFrameProcessingAttributeRange()

Range: Use IBlackmagicRawConstants::GetFrameProcessingAttributeRange()

Exports a single frame of the currently viewed video frame.

Custom Gamma Controls

 Blackmagic Design Film

Custom Gamma Controls 14

Range: Use IBlackmagicRawConstants::GetClipProcessingAttributeList()

Range: Use IBlackmagicRawConstants::GetClipProcessingAttributeList()

Range: Use IBlackmagicRawConstants::GetClipProcessingAttributeList()

Custom Gamma Controls 15

Range: Use IBlackmagicRawConstants::GetClipProcessingAttributeList()

Range: Use IBlackmagicRawConstants::GetClipProcessingAttributeList()

Range: Use IBlackmagicRawConstants::GetClipProcessingAttributeList()

Range: Use IBlackmagicRawConstants::GetClipProcessingAttributeList()

Set Video Black Level

Custom Gamma Controls 16

Default: Read from metadata.

Options: Use IBlackmagicRawConstants::GetClipProcessingAttributeList()

Example: For clips that have an embedded or sidecar 3DLUT available,

Windows unsigned int

Windows signed char

Windows unsigned char

Windows unsigned short

Windows unsigned int

Windows long long

Options: Use IBlackmagicRawConstants::GetClipProcessingAttributeList()

Options: Use IBlackmagicRawConstants::GetClipProcessingAttributeList()

Options: Use IBlackmagicRawConstants::GetClipProcessingAttributeList()

Options: Use IBlackmagicRawConstants::GetFrameProcessingAttributeRange()

Range: Use IBlackmagicRawConstants::GetFrameProcessingAttributeRange()

Range: Use IBlackmagicRawConstants::GetFrameProcessingAttributeRange()

Range: Use IBlackmagicRawConstants::GetFrameProcessingAttributeRange()

Blackmagic Design Film

Range: Use IBlackmagicRawConstants::GetClipProcessingAttributeList()

Range: Use IBlackmagicRawConstants::GetClipProcessingAttributeList()

Range: Use IBlackmagicRawConstants::GetClipProcessingAttributeList()

Range: Use IBlackmagicRawConstants::GetClipProcessingAttributeList()

Range: Use IBlackmagicRawConstants::GetClipProcessingAttributeList()

Range: Use IBlackmagicRawConstants::GetClipProcessingAttributeList()

Range: Use IBlackmagicRawConstants::GetClipProcessingAttributeList()

Options: Use IBlackmagicRawConstants::GetClipProcessingAttributeList()