nx_camera_sdk  1.0
Camera SDK
Public Types | Public Member Functions | List of all members
nxcip::DtsArchiveReader Class Referenceabstract

Provides access to archive, stored on camera. More...

#include <camera_plugin.h>

Inheritance diagram for nxcip::DtsArchiveReader:
nxpl::PluginInterface ArchiveReader

Public Types

enum  Capabilities { reverseGopModeCapability = 0x01, skipFramesCapability = 0x02, motionDataCapability = 0x04 }
 

Public Member Functions

virtual unsigned int getCapabilities () const =0
 Returns bit mask with supported capabilities.
 
virtual int open ()=0
 Initialize connection to archive. More...
 
virtual StreamReadergetStreamReader ()=0
 Returns stream reader. More...
 
virtual UsecUTCTimestamp startTime () const =0
 Returns timestamp (usec (microseconds) since 1970-01-01, UTC) of oldest data, present in the archive. More...
 
virtual UsecUTCTimestamp endTime () const =0
 Returns timestamp (usec (microseconds) since 1970-01-01, UTC) of newest data, present in the archive. More...
 
virtual int seek (unsigned int cSeq, UsecUTCTimestamp timestamp, bool findKeyFrame, UsecUTCTimestamp *selectedPosition)=0
 Seek to specified posiition in stream. More...
 
virtual int setReverseMode (unsigned int cSeq, bool isReverse, UsecUTCTimestamp timestamp, UsecUTCTimestamp *selectedPosition)=0
 Set playback direction (forward/reverse) More...
 
virtual bool isReverseModeEnabled () const =0
 Returns true if reverse mode is currently on.
 
virtual int setMotionDataEnabled (bool motionPresent)=0
 Toggle motion data in media stream on/off. More...
 
virtual int setQuality (MediaStreamQuality quality, bool waitForKeyFrame)=0
 Select media stream quality (used for dynamic media stream adaptation) More...
 
virtual int playRange (unsigned int cSeq, UsecUTCTimestamp start, UsecUTCTimestamp endTimeHint, unsigned int step)=0
 Play time range [start; end) skipping frames. More...
 
virtual void getLastErrorString (char *errorString) const =0
 Returns text description of the last error. More...
 
- Public Member Functions inherited from nxpl::PluginInterface
virtual void * queryInterface (const nxpl::NX_GUID &interfaceID)=0
 Cast to type, specified by interfaceID. More...
 
virtual int addRef () const =0
 Increment reference counter. More...
 
virtual int releaseRef () const =0
 Decrement reference counter. More...
 

Detailed Description

Provides access to archive, stored on camera.

Implements methods to manage (seek, select playback direction, select stream quality) archive playback.

Media stream is provided by nxcip::StreamReader instance returned by nxcip::DtsArchiveReader::getStreamReader().

cSeq (command sequence counter)
Methods DtsArchiveReader::seek, DtsArchiveReader::setReverseMode, DtsArchiveReader::playRange accept cSeq value which they MUST use in every media packet generated in response to this command

It is not required, that archive contains data from all encoders

Note
By default, archive is positioned to the beginning, quality set to high and playback direction is forward
Methods of this class can be called in thread different from thread calling StreamReader::getNextData()

Member Enumeration Documentation

◆ Capabilities

Enumerator
reverseGopModeCapability 

Signals that reverse playback by GOP (group of picture) reordering is supported.

Plugin MAY support backward playback by GOP (group of picture) reordering. If this is not supported, reverse playback is emulated by server.
This capability is not required but can increase performance.
Reverse gop playback is organized in following way:
Assume, we have media stream consisting of 6 gop:

------ ------ ------ ------ ------ ------
|GOP1| |GOP2| |GOP3| |GOP4| |GOP5| |GOP6|
------ ------ ------ ------ ------ ------

To be able to play it in reverse mode, plugin passes GOPs in reverse mode (RB is "reverse block"):

------ | ------ | ------ | ------ | ------ | ------
|GOP6| | |GOP5| | |GOP4| | |GOP3| | |GOP2| | |GOP1|
------ | ------ | ------ | ------ | ------ | ------
RB1 | RB2 | RB3 | RB4 | RB5 | RB6

Reverse block can consist of multiple GOP. E.g.:

------ ------ | ------ ------ | ------ ------
|GOP5| |GOP6| | |GOP3| |GOP4| | |GOP1| |GOP2|
------ ------ | ------ ------ | ------ ------
RB1 | RB2 | RB3

Such stream is played by decoding the whole RB and then playing decoded frames in reverse order

Note
Frames within each GOP MUST be in their original order (i.e., decoding order)
Once again, this is an optional functionality for plugin
skipFramesCapability 

frame skipping with DtsArchiveReader::setSkipFrames method is supported

Note
This funtionality is optional. Helps for better performance
motionDataCapability 

motion data can be provided in media stream

Member Function Documentation

◆ endTime()

virtual UsecUTCTimestamp nxcip::DtsArchiveReader::endTime ( ) const
pure virtual

Returns timestamp (usec (microseconds) since 1970-01-01, UTC) of newest data, present in the archive.

This value can be changed at any time (if record is ongoing)

Implemented in ArchiveReader.

◆ getLastErrorString()

virtual void nxcip::DtsArchiveReader::getLastErrorString ( char *  errorString) const
pure virtual

Returns text description of the last error.

Parameters
[out]errorStringBuffer of size MAX_TEXT_LEN

Implemented in ArchiveReader.

◆ getStreamReader()

virtual StreamReader* nxcip::DtsArchiveReader::getStreamReader ( )
pure virtual

Returns stream reader.

DtsArchiveReader instance holds reference to returned StreamReader instance

Implemented in ArchiveReader.

◆ open()

virtual int nxcip::DtsArchiveReader::open ( )
pure virtual

Initialize connection to archive.

Returns
zero on success, error code in case on failure. Use DtsArchiveReader::getLastErrorString to get error description

Implemented in ArchiveReader.

◆ playRange()

virtual int nxcip::DtsArchiveReader::playRange ( unsigned int  cSeq,
UsecUTCTimestamp  start,
UsecUTCTimestamp  endTimeHint,
unsigned int  step 
)
pure virtual

Play time range [start; end) skipping frames.

Tells to skip media packets for inter-packet timestamp gap to be at least step usec (microseconds). When frame skipping is implied, audio packets SHOULD not be reported

Parameters
[in]cSeqNew value of command sequence counter
startPosition to seek to
endTimeHintUsed to hint implementation that packets with greater timestamp are of no interest. Implementation MAY NOT cache (if it does) data with greater timestamp
stepIf 0, no frames MUST be skipped
Note
Used only if DtsArchiveReader::skipFramesCapability is set
If frame skipping is enabled only key frames SHOULD be provided by StreamReader::getNextData call
This is used to generate thumbnails
This funtionality is optional

Implemented in ArchiveReader.

◆ seek()

virtual int nxcip::DtsArchiveReader::seek ( unsigned int  cSeq,
UsecUTCTimestamp  timestamp,
bool  findKeyFrame,
UsecUTCTimestamp *  selectedPosition 
)
pure virtual

Seek to specified posiition in stream.

Implementation is allowed to jump to frame with timestamp next to requested (i.e., lower_bound algorithm is implied to find frame)

Parameters
[in]cSeqNew value of command sequence counter
[in]timestamptimestamp to seek to
[in]findKeyFrameIf true, MUST jump to key-frame only (selected frame timestamp MUST be equal or less than requested)
[out]selectedPositionTimestamp of actually selected position
Returns

  • NX_NO_ERROR on success
  • NX_NO_DATA if timestamp is greater than timestamp of the last frame of the archive (in case of if forward play) and if timestamp is less than timestamp of the first frame of the archive (in case of reverse play)
Note
This funtionality is required

Implemented in ArchiveReader.

◆ setMotionDataEnabled()

virtual int nxcip::DtsArchiveReader::setMotionDataEnabled ( bool  motionPresent)
pure virtual

Toggle motion data in media stream on/off.

Returns
NX_NO_ERROR on success, otherwise - error code
Note
This funtionality is optional

Implemented in ArchiveReader.

◆ setQuality()

virtual int nxcip::DtsArchiveReader::setQuality ( MediaStreamQuality  quality,
bool  waitForKeyFrame 
)
pure virtual

Select media stream quality (used for dynamic media stream adaptation)

Media stream switching may not occur immediately, depending on waitForKeyFrame argument

Parameters
[in]qualityMedia stream quality
[in]waitForKeyFrameIf true, implementation SHOULD switch only on reaching next key frame of new stream. If false, StreamReader instance SHOULD switch immediately to the key frame of new stream with greatest pts, not exceeding current
Returns
NX_NO_ERROR on success (requested data present in the stream). Otherwise - error code.
If requested quality is not supported, NX_NO_DATA is returned
Note
nxcip::msqDefault MUST always be supported
This funtionality is optional

Implemented in ArchiveReader.

◆ setReverseMode()

virtual int nxcip::DtsArchiveReader::setReverseMode ( unsigned int  cSeq,
bool  isReverse,
UsecUTCTimestamp  timestamp,
UsecUTCTimestamp *  selectedPosition 
)
pure virtual

Set playback direction (forward/reverse)

If timestamp is not equal to INVALID_TIMESTAMP_VALUE, seek is performed along with playback direction change

Parameters
[in]cSeqNew value of command sequence counter
[in]isReverseIf true, playback
[in]positionif not INVALID_TIMESTAMP_VALUE, playback SHOULD jump to this position (with rules, defined for DtsArchiveReader::seek)
[out]selectedPositionTimestamp of actually selected position
Note
This method is used only if DtsArchiveReader::reverseModeCapability is supported
Returns
NX_NO_ERROR on success, otherwise - error code
Note
This funtionality is optional
If end-of-stream reached with reverse mode, packets of type dptEmpty MUST have flag MediaDataPacket::fReverseStream set

Implemented in ArchiveReader.

◆ startTime()

virtual UsecUTCTimestamp nxcip::DtsArchiveReader::startTime ( ) const
pure virtual

Returns timestamp (usec (microseconds) since 1970-01-01, UTC) of oldest data, present in the archive.

This value can be changed at any time (if record is ongoing)

Implemented in ArchiveReader.


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