AJA NTV2 SDK  17.5.0.1242
NTV2 SDK 17.5.0.1242
NTV2FormatDescriptor Class Reference

Describes a video frame for a given video standard or format and pixel format, including the total number of lines, number of pixels per line, line pitch, and which line contains the start of active video. More...

#include <ntv2formatdescriptor.h>

Public Member Functions

void MakeInvalid (void)
 Resets me into an invalid (NULL) state. More...
 
Constructors
 NTV2FormatDescriptor ()
 My default constructor initializes me in an "invalid" state. More...
 
 NTV2FormatDescriptor (const ULWord inNumLines, const ULWord inNumPixels, const ULWord inLinePitch, const ULWord in1stActiveLine=0, const UByte inNumLumaBits=0, const UByte inNumChromaBits=0, const UByte inNumAlphaBits=0)
 Construct from line and pixel count, plus line pitch. More...
 
 NTV2FormatDescriptor (const NTV2Standard inStandard, const NTV2FrameBufferFormat inFrameBufferFormat, const NTV2VANCMode inVancMode=NTV2_VANCMODE_OFF)
 Constructs me from the given video standard, pixel format, and VANC settings. More...
 
 NTV2FormatDescriptor (const NTV2VideoFormat inVideoFormat, const NTV2FrameBufferFormat inFrameBufferFormat, const NTV2VANCMode inVancMode=NTV2_VANCMODE_OFF)
 Constructs me from the given video format, pixel format and VANC settings. More...
 
Inquiry
bool IsValid (void) const
 
ULWord GetVerticalSampleRatio (const UWord inPlaneIndex0=0) const
 
ULWord GetTotalRasterBytes (const UWord inPlaneIndex0=0) const
 
ULWord GetTotalBytes (void) const
 
ULWord GetVideoWriteSize (ULWord inPageSize=4096UL) const
 
ULWord GetVisibleRasterBytes (const UWord inPlaneIndex0=0) const
 
ULWord GetBytesPerRow (const UWord inPlaneIndex0=0) const
 
std::string PlaneToString (const UWord inPlaneIndex0) const
 
UWord ByteOffsetToPlane (const ULWord inByteOffset) const
 
UWord ByteOffsetToRasterLine (const ULWord inByteOffset) const
 
bool IsAtLineStart (ULWord inByteOffset) const
 
ULWord GetRasterHeight (const bool inVisibleOnly=false) const
 
ULWord GetFullRasterHeight (void) const
 
ULWord GetFirstActiveLine (void) const
 
ULWord GetVisibleRasterHeight (void) const
 
bool GetRowBuffer (const NTV2Buffer &inFrameBuffer, NTV2Buffer &inOutRowBuffer, const ULWord inRowIndex0, const UWord inPlaneIndex0=0) const
 Answers with an NTV2Buffer that describes the given row (and plane) given the NTV2Buffer that describes the frame buffer. More...
 
const void * GetRowAddress (const void *pInStartAddress, const ULWord inRowIndex0, const UWord inPlaneIndex0=0) const
 
void * GetWriteableRowAddress (void *pInStartAddress, const ULWord inRowIndex0, const UWord inPlaneIndex0=0) const
 
ULWord RasterLineToByteOffset (const ULWord inRowIndex0, const UWord inPlaneIndex0=0) const
 
UByteGetTopVisibleRowAddress (UByte *pInStartAddress) const
 
bool GetFirstChangedRow (const void *pInStartAddress1, const void *pInStartAddress2, ULWord &outFirstChangedRowNum) const
 Compares two buffers line-by-line (using my description of the buffer contents). More...
 
bool GetChangedLines (NTV2RasterLineOffsets &outDiffs, const void *pInBuffer1, const void *pInBuffer2, const ULWord inMaxLines=0) const
 Compares two buffers line-by-line (using my description of the buffer contents). More...
 
NTV2FrameDimensions GetFullRasterDimensions (void) const
 
NTV2FrameDimensions GetVisibleRasterDimensions (void) const
 
bool GetSMPTELineNumber (const ULWord inLineOffset, ULWord &outSMPTELine, bool &outIsField2) const
 Answers with the equivalent SMPTE line number for the given line offset into the frame buffer I describe. More...
 
bool GetLineOffsetFromSMPTELine (const ULWord inSMPTELine, ULWord &outLineOffset) const
 Answers with the equivalent line offset into the raster I describe for the given SMPTE line number. More...
 
NTV2SegmentedXferInfoGetSegmentedXferInfo (NTV2SegmentedXferInfo &inSegmentInfo, const bool inIsSource=true) const
 Sets the given NTV2SegmentedXferInfo to match my raster, as a source or destination. More...
 
bool operator== (const NTV2FormatDescriptor &inRHS) const
 
std::ostream & Print (std::ostream &inOutStream, const bool inDetailed=true) const
 Writes a human-readable description of me into the given output stream. More...
 
std::ostream & PrintSMPTELineNumber (std::ostream &inOutStream, const ULWord inLineOffset, const bool inForTextMode=false) const
 Writes the given frame buffer line offset as a formatted SMPTE line number into the given output stream. More...
 
bool Is2KFormat (void) const
 

Public Attributes

ULWord numLines
 Height – total number of lines. More...
 
ULWord numPixels
 Width – total number of pixels per line. More...
 
ULWord linePitch
 Number of 32-bit words per line – shadows mLinePitch[0] / sizeof(ULWord) More...
 
ULWord firstActiveLine
 First active line of video (0 if NTV2_VANCMODE_OFF) More...
 

Friends

class CNTV2CaptionRenderer
 

Detailed Description

Describes a video frame for a given video standard or format and pixel format, including the total number of lines, number of pixels per line, line pitch, and which line contains the start of active video.

Note
It is possible to construct a format descriptor that is not supported by the AJA device.

Definition at line 41 of file ntv2formatdescriptor.h.

Constructor & Destructor Documentation

◆ NTV2FormatDescriptor() [1/4]

NTV2FormatDescriptor::NTV2FormatDescriptor ( )
explicit

My default constructor initializes me in an "invalid" state.

My default constructor

Definition at line 812 of file ntv2formatdescriptor.cpp.

◆ NTV2FormatDescriptor() [2/4]

NTV2FormatDescriptor::NTV2FormatDescriptor ( const ULWord  inNumLines,
const ULWord  inNumPixels,
const ULWord  inLinePitch,
const ULWord  in1stActiveLine = 0,
const UByte  inNumLumaBits = 0,
const UByte  inNumChromaBits = 0,
const UByte  inNumAlphaBits = 0 
)
explicit

Construct from line and pixel count, plus line pitch.

Parameters
[in]inNumLinesSpecifies the total number of lines.
[in]inNumPixelsSpecifies the total number of pixels.
[in]inLinePitchSpecifies the line pitch as the number of 32-bit words per line.
[in]in1stActiveLineOptionally specifies the first active line of video, where zero is the first (top) line. Defaults to zero.
[in]inNumLumaBitsOptionally specifies the number of luma bits. Defaults to zero.
[in]inNumChromaBitsOptionally specifies the number of chroma bits. Defaults to zero.
[in]inNumAlphaBitsOptionally specifies the number of alpha bits. Defaults to zero.

Definition at line 818 of file ntv2formatdescriptor.cpp.

◆ NTV2FormatDescriptor() [3/4]

NTV2FormatDescriptor::NTV2FormatDescriptor ( const NTV2Standard  inStandard,
const NTV2FrameBufferFormat  inFrameBufferFormat,
const NTV2VANCMode  inVancMode = NTV2_VANCMODE_OFF 
)
explicit

Constructs me from the given video standard, pixel format, and VANC settings.

Parameters
[in]inStandardSpecifies the video standard being used.
[in]inFrameBufferFormatSpecifies the pixel format of the frame buffer.
[in]inVancModeSpecifies the VANC mode. Defaults to OFF.

Definition at line 651 of file ntv2formatdescriptor.cpp.

◆ NTV2FormatDescriptor() [4/4]

NTV2FormatDescriptor::NTV2FormatDescriptor ( const NTV2VideoFormat  inVideoFormat,
const NTV2FrameBufferFormat  inFrameBufferFormat,
const NTV2VANCMode  inVancMode = NTV2_VANCMODE_OFF 
)
explicit

Constructs me from the given video format, pixel format and VANC settings.

Parameters
[in]inVideoFormatSpecifies the video format being used.
[in]inFrameBufferFormatSpecifies the pixel format of the frame buffer.
[in]inVancModeSpecifies the VANC mode.

Definition at line 756 of file ntv2formatdescriptor.cpp.

Member Function Documentation

◆ ByteOffsetToPlane()

UWord NTV2FormatDescriptor::ByteOffsetToPlane ( const ULWord  inByteOffset) const
Returns
The zero-based index number of the plane that contains the byte at the given offset, or 0xFFFF if the offset is not within any plane in the buffer.
Parameters
[in]inByteOffsetThe offset, in bytes, to the byte of interest in the frame.

Definition at line 929 of file ntv2formatdescriptor.cpp.

◆ ByteOffsetToRasterLine()

UWord NTV2FormatDescriptor::ByteOffsetToRasterLine ( const ULWord  inByteOffset) const
Returns
The zero-based index number of the raster line (row) that contains the byte at the given offset, or 0xFFFF if the offset does not fall within any plane or line in the buffer.
Parameters
[in]inByteOffsetThe offset, in bytes, to the byte of interest in the raster buffer.

Definition at line 946 of file ntv2formatdescriptor.cpp.

◆ GetBytesPerRow()

ULWord NTV2FormatDescriptor::GetBytesPerRow ( const UWord  inPlaneIndex0 = 0) const
inline
Returns
The number of bytes per row/line of the raster.
Parameters
[in]inPlaneIndex0Specifies the plane of interest. Defaults to zero.

Definition at line 146 of file ntv2formatdescriptor.h.

◆ GetChangedLines()

bool NTV2FormatDescriptor::GetChangedLines ( NTV2RasterLineOffsets outDiffs,
const void *  pInBuffer1,
const void *  pInBuffer2,
const ULWord  inMaxLines = 0 
) const

Compares two buffers line-by-line (using my description of the buffer contents).

Parameters
[out]outDiffsReceives the ordered sequence of line offsets of the lines that differed. This will be empty if the two buffers are identical (or if an error occurs).
[in]pInBuffer1Specifies the non-NULL address of the first memory buffer whose contents are to be compared.
[in]pInBuffer2Specifies the non-NULL address of the second memory buffer whose contents are to be compared.
[in]inMaxLinesOptionally specifies the maximum number of lines to compare. If zero, all lines are compared. Defaults to zero (all lines).
Returns
True if successful; otherwise false.
Note
The buffers must be large enough to accommodate my video standard/format or else a memory access violation will occur.

Definition at line 1082 of file ntv2formatdescriptor.cpp.

◆ GetFirstActiveLine()

ULWord NTV2FormatDescriptor::GetFirstActiveLine ( void  ) const
inline
Returns
The zero-based index number of the first active (visible) line in the raster. This will be zero for non-VANC rasters.

Definition at line 186 of file ntv2formatdescriptor.h.

◆ GetFirstChangedRow()

bool NTV2FormatDescriptor::GetFirstChangedRow ( const void *  pInStartAddress1,
const void *  pInStartAddress2,
ULWord outFirstChangedRowNum 
) const

Compares two buffers line-by-line (using my description of the buffer contents).

Parameters
[in]pInStartAddress1A valid, non-NULL pointer to the start of the first raster buffer.
[in]pInStartAddress2A valid, non-NULL pointer to the start of the second raster buffer.
[out]outFirstChangedRowNumReceives the zero-based row number of the first row that's different, or 0xFFFFFFFF if identical.
Returns
True if successful; otherwise false.

Definition at line 1058 of file ntv2formatdescriptor.cpp.

◆ GetFullRasterDimensions()

NTV2FrameDimensions NTV2FormatDescriptor::GetFullRasterDimensions ( void  ) const
Returns
The full-raster NTV2FrameDimensions (including VANC lines, if any).

Definition at line 1262 of file ntv2formatdescriptor.cpp.

◆ GetFullRasterHeight()

ULWord NTV2FormatDescriptor::GetFullRasterHeight ( void  ) const
inline
Returns
The full height of the raster, in lines (including VANC, if any).

Definition at line 181 of file ntv2formatdescriptor.h.

◆ GetLineOffsetFromSMPTELine()

bool NTV2FormatDescriptor::GetLineOffsetFromSMPTELine ( const ULWord  inSMPTELine,
ULWord outLineOffset 
) const

Answers with the equivalent line offset into the raster I describe for the given SMPTE line number.

Parameters
[in]inSMPTELineSpecifies the SMPTE line number.
[out]outLineOffsetReceives the zero-based line offset into the raster I describe.
Returns
True if successful; otherwise false.

Definition at line 1204 of file ntv2formatdescriptor.cpp.

◆ GetRasterHeight()

ULWord NTV2FormatDescriptor::GetRasterHeight ( const bool  inVisibleOnly = false) const
inline
Returns
The height of the raster, in lines.
Parameters
[in]inVisibleOnlySpecify true to return just the visible height; otherwise false (the default) to return the full height.

Definition at line 176 of file ntv2formatdescriptor.h.

◆ GetRowAddress()

const void * NTV2FormatDescriptor::GetRowAddress ( const void *  pInStartAddress,
const ULWord  inRowIndex0,
const UWord  inPlaneIndex0 = 0 
) const
Returns
A pointer to the start of the given row in the given buffer, or NULL if row index is bad (using my description of the buffer contents).
Parameters
[in]pInStartAddressA pointer to the raster buffer.
[in]inRowIndex0Specifies the row of interest in the buffer, where zero is the topmost row.
[in]inPlaneIndex0Specifies the plane of interest. Defaults to zero.

Definition at line 1001 of file ntv2formatdescriptor.cpp.

◆ GetRowBuffer()

bool NTV2FormatDescriptor::GetRowBuffer ( const NTV2Buffer inFrameBuffer,
NTV2Buffer inOutRowBuffer,
const ULWord  inRowIndex0,
const UWord  inPlaneIndex0 = 0 
) const

Answers with an NTV2Buffer that describes the given row (and plane) given the NTV2Buffer that describes the frame buffer.

Parameters
[in]inFrameBufferSpecifies the frame buffer (that includes all planes, if planar).
inOutRowBufferReceives the NTV2Buffer that references the row (and plane) in the frame buffer.
[in]inRowIndex0Specifies the row of interest in the buffer, where zero is the topmost row.
[in]inPlaneIndex0Optionally specifies the plane of interest. Defaults to zero.
Returns
True if successful; otherwise false.

Definition at line 975 of file ntv2formatdescriptor.cpp.

◆ GetSegmentedXferInfo()

NTV2SegmentedXferInfo & NTV2FormatDescriptor::GetSegmentedXferInfo ( NTV2SegmentedXferInfo inSegmentInfo,
const bool  inIsSource = true 
) const

Sets the given NTV2SegmentedXferInfo to match my raster, as a source or destination.

Parameters
inSegmentInfoSpecifies the segmented transfer object to modify.
[in]inIsSourceSpecify 'true' (the default) to set the "source" aspect of the transfer info object; otherwise 'false' to set the "destination" aspect of it.
Returns
A non-const reference to the NTV2SegmentedXferInfo object.

Definition at line 1273 of file ntv2formatdescriptor.cpp.

◆ GetSMPTELineNumber()

bool NTV2FormatDescriptor::GetSMPTELineNumber ( const ULWord  inLineOffset,
ULWord outSMPTELine,
bool &  outIsField2 
) const

Answers with the equivalent SMPTE line number for the given line offset into the frame buffer I describe.

Parameters
[in]inLineOffsetSpecifies the zero-based line offset into the frame buffer that I describe.
[out]outSMPTELineReceives the equivalent SMPTE line number.
[out]outIsField2Receives true if the line number is associated with Field 2 (interlaced only); otherwise false.
Returns
True if successful; otherwise false.

Definition at line 1172 of file ntv2formatdescriptor.cpp.

◆ GetTopVisibleRowAddress()

UByte* NTV2FormatDescriptor::GetTopVisibleRowAddress ( UByte pInStartAddress) const
inline
Returns
A pointer to the start of the first visible row in the given buffer, or NULL if invalid (using my description of the buffer contents).
Parameters
[in]pInStartAddressA pointer to the raster buffer.

Definition at line 236 of file ntv2formatdescriptor.h.

◆ GetTotalBytes()

ULWord NTV2FormatDescriptor::GetTotalBytes ( void  ) const
Returns
The total number of bytes required to hold the raster, including any VANC, and all planes of planar formats.

Definition at line 855 of file ntv2formatdescriptor.cpp.

◆ GetTotalRasterBytes()

ULWord NTV2FormatDescriptor::GetTotalRasterBytes ( const UWord  inPlaneIndex0 = 0) const
inline
Returns
The total number of bytes required to hold the raster plane, including any VANC lines. Returns zero upon error.
Note
To determine the byte count of all planes of a planar format, call GetTotalBytes.
Parameters
[in]inPlaneIndex0Specifies the plane of interest. Defaults to zero.

Definition at line 120 of file ntv2formatdescriptor.h.

◆ GetVerticalSampleRatio()

ULWord NTV2FormatDescriptor::GetVerticalSampleRatio ( const UWord  inPlaneIndex0 = 0) const
Returns
The number of samples spanned per sample used, usually 1 for most formats. Returns zero if an invalid plane is specified.
Parameters
[in]inPlaneIndex0Specifies the plane of interest. Defaults to zero.
Note
Used for asymmetric vertical sampling, such as 3-plane 4:2:0 formats, where the returned value is 1 for the Y plane, and 2 for the Cb/Cr planes.

Definition at line 885 of file ntv2formatdescriptor.cpp.

◆ GetVideoWriteSize()

ULWord NTV2FormatDescriptor::GetVideoWriteSize ( ULWord  inPageSize = 4096UL) const
Returns
The result of GetTotalBytes rounded up to the nearest page size.
Parameters
[in]inPageSizeOptionally specifies the page size to use. Defaults to 4096 (4K) bytes.

Definition at line 866 of file ntv2formatdescriptor.cpp.

◆ GetVisibleRasterBytes()

ULWord NTV2FormatDescriptor::GetVisibleRasterBytes ( const UWord  inPlaneIndex0 = 0) const
inline
Returns
The total number of bytes required to hold the visible raster (i.e. active lines after any VANC lines).
Parameters
[in]inPlaneIndex0Specifies the plane of interest. Defaults to zero, the first plane.

Definition at line 140 of file ntv2formatdescriptor.h.

◆ GetVisibleRasterDimensions()

NTV2FrameDimensions NTV2FormatDescriptor::GetVisibleRasterDimensions ( void  ) const
Returns
The visible NTV2FrameDimensions (excluding VANC lines, if any).

Definition at line 1267 of file ntv2formatdescriptor.cpp.

◆ GetVisibleRasterHeight()

ULWord NTV2FormatDescriptor::GetVisibleRasterHeight ( void  ) const
inline
Returns
The visible height of the raster, in lines (excluding VANC, if any).

Definition at line 191 of file ntv2formatdescriptor.h.

◆ GetWriteableRowAddress()

void * NTV2FormatDescriptor::GetWriteableRowAddress ( void *  pInStartAddress,
const ULWord  inRowIndex0,
const UWord  inPlaneIndex0 = 0 
) const
Returns
A non-const pointer to the start of the given row in the given buffer, or NULL if row index is bad (using my description of the buffer contents).
Parameters
[in]pInStartAddressA non-const pointer to the raster buffer.
[in]inRowIndex0Specifies the row of interest in the buffer, where zero is the topmost row.
[in]inPlaneIndex0Specifies the plane of interest. Defaults to zero.

Definition at line 1022 of file ntv2formatdescriptor.cpp.

◆ Is2KFormat()

bool NTV2FormatDescriptor::Is2KFormat ( void  ) const
Returns
True if I was created with a 2Kx1080 video format.

Definition at line 902 of file ntv2formatdescriptor.cpp.

◆ IsAtLineStart()

bool NTV2FormatDescriptor::IsAtLineStart ( ULWord  inByteOffset) const
Returns
True if the given byte offset is at the start of a new raster line (row); otherwise false.
Parameters
[in]inByteOffsetThe offset, in bytes, to the byte of interest in the frame.

Definition at line 961 of file ntv2formatdescriptor.cpp.

◆ IsValid()

bool NTV2FormatDescriptor::IsValid ( void  ) const
inline
Returns
True if valid – i.e. non-zero line count, non-zero pixel count, non-zero plane count, non-zero line pitch (1st plane), and a non-zero bit count (for luma or chroma).

Definition at line 100 of file ntv2formatdescriptor.h.

◆ MakeInvalid()

void NTV2FormatDescriptor::MakeInvalid ( void  )

Resets me into an invalid (NULL) state.

Definition at line 839 of file ntv2formatdescriptor.cpp.

◆ operator==()

bool NTV2FormatDescriptor::operator== ( const NTV2FormatDescriptor inRHS) const
Returns
True if I'm equal to the given NTV2FormatDescriptor.
Parameters
[in]inRHSThe right-hand-side operand that I'll be compared with.

Definition at line 912 of file ntv2formatdescriptor.cpp.

◆ PlaneToString()

string NTV2FormatDescriptor::PlaneToString ( const UWord  inPlaneIndex0) const
Returns
A string containing a human-readable name for the specified plane.

Definition at line 920 of file ntv2formatdescriptor.cpp.

◆ Print()

ostream & NTV2FormatDescriptor::Print ( std::ostream &  inOutStream,
const bool  inDetailed = true 
) const

Writes a human-readable description of me into the given output stream.

Parameters
inOutStreamThe output stream to be written into.
[in]inDetailedIf true (the default), writes a detailed description; otherwise writes a brief one.
Returns
The output stream I was handed.

Definition at line 1112 of file ntv2formatdescriptor.cpp.

◆ PrintSMPTELineNumber()

ostream & NTV2FormatDescriptor::PrintSMPTELineNumber ( std::ostream &  inOutStream,
const ULWord  inLineOffset,
const bool  inForTextMode = false 
) const

Writes the given frame buffer line offset as a formatted SMPTE line number into the given output stream.

Parameters
inOutStreamThe output stream to be written into.
[in]inLineOffsetSpecifies the zero-based line offset in the frame buffer.
[in]inForTextModeDefaults to false. If true, omits the space between the field indicator and the line number, and adds leading zeroes to line number.
Returns
The output stream I was handed.

Definition at line 1246 of file ntv2formatdescriptor.cpp.

◆ RasterLineToByteOffset()

ULWord NTV2FormatDescriptor::RasterLineToByteOffset ( const ULWord  inRowIndex0,
const UWord  inPlaneIndex0 = 0 
) const
Returns
The absolute byte offset from the start of the frame buffer to the start of the given raster line in the given plane (or 0xFFFFFFFF if the row and/or plane indexes are bad).
Note
This function assumes that the planes contiguously abut each other in memory, in ascending address order.
Parameters
[in]inRowIndex0Specifies the row of interest in the buffer, where zero is the topmost row.
[in]inPlaneIndex0Specifies the plane of interest. Defaults to zero.

Definition at line 1040 of file ntv2formatdescriptor.cpp.

Friends And Related Function Documentation

◆ CNTV2CaptionRenderer

friend class CNTV2CaptionRenderer
friend

Definition at line 347 of file ntv2formatdescriptor.h.

Member Data Documentation

◆ firstActiveLine

ULWord NTV2FormatDescriptor::firstActiveLine

First active line of video (0 if NTV2_VANCMODE_OFF)

Definition at line 357 of file ntv2formatdescriptor.h.

◆ linePitch

ULWord NTV2FormatDescriptor::linePitch

Number of 32-bit words per line – shadows mLinePitch[0] / sizeof(ULWord)

Definition at line 356 of file ntv2formatdescriptor.h.

◆ numLines

ULWord NTV2FormatDescriptor::numLines

Height – total number of lines.

Definition at line 354 of file ntv2formatdescriptor.h.

◆ numPixels

ULWord NTV2FormatDescriptor::numPixels

Width – total number of pixels per line.

Definition at line 355 of file ntv2formatdescriptor.h.


The documentation for this class was generated from the following files: