FrameMapper.h
Go to the documentation of this file.
/**
* @file
* @brief Header file for the FrameMapper class
* @author Jonathan Thomas <jonathan@openshot.org>
*
* @section LICENSE
*
* Copyright (c) 2008-2014 OpenShot Studios, LLC
* <http://www.openshotstudios.com/>. This file is part of
* OpenShot Library (libopenshot), an open-source project dedicated to
* delivering high quality video editing and animation solutions to the
* world. For more information visit <http://www.openshot.org/>.
*
* OpenShot Library (libopenshot) is free software: you can redistribute it
* and/or modify it under the terms of the GNU Lesser General Public License
* as published by the Free Software Foundation, either version 3 of the
* License, or (at your option) any later version.
*
* OpenShot Library (libopenshot) is distributed in the hope that it will be
* useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public License
* along with OpenShot Library. If not, see <http://www.gnu.org/licenses/>.
*/
#ifndef OPENSHOT_FRAMEMAPPER_H
#define OPENSHOT_FRAMEMAPPER_H
#include <assert.h>
#include <iostream>
#include <math.h>
#include <vector>
#include <memory>
#include "CacheMemory.h"
#include "ReaderBase.h"
#include "Frame.h"
#include "Fraction.h"
#include "Exceptions.h"
#include "KeyFrame.h"
// Include FFmpeg headers and macros
#include "FFmpegUtilities.h"
#include "OpenMPUtilities.h"
using namespace std;
namespace openshot
{
/**
* @brief This enumeration determines how frame rates are increased or decreased.
*
* Pull-down techniques are only needed to remove artificial fields added when converting
* between 24 fps (film) and television fps (29.97 fps NTSC or 25 fps PAL).
*/
enum PulldownType
{
PULLDOWN_CLASSIC, ///< Classic 2:3:2:3 pull-down
PULLDOWN_ADVANCED, ///< Advanced 2:3:3:2 pull-down (minimal dirty frames)
PULLDOWN_NONE, ///< Do not apply pull-down techniques, just repeat or skip entire frames
};
/**
* @brief This struct holds a single field (half a frame).
*
* A frame of video is made up of 2 fields (half a frame). This struct points to which original
* frame, and whether this is the ODD or EVEN lines (i.e. top or bottom).
*/
struct Field
{
int64_t Frame;
bool isOdd;
Field() : Frame(0), isOdd(true) { };
Field(int64_t frame, bool isodd)
{
Frame = frame;
isOdd = isodd;
}
};
/**
* @brief This struct holds a the range of samples needed by this frame
*
* When frame rate is changed, the audio needs to be redistributed among the remaining
* frames. This struct holds the range samples needed by the this frame.
*/
struct SampleRange
{
int64_t frame_start;
int sample_start;
int64_t frame_end;
int sample_end;
int total;
};
/**
* @brief This struct holds two fields which together make up a complete video frame.
*
* These fields can point at different original frame numbers, for example the odd lines from
* frame 3, and the even lines of frame 4, if required by a pull-down technique.
*/
struct MappedFrame
{
Field Odd;
Field Even;
SampleRange Samples;
};
/**
* @brief This class creates a mapping between 2 different frame rates, applying a specific pull-down technique.
*
* This class creates a mapping between 2 different video files, and supports many pull-down techniques,
* such as 2:3:2:3 or 2:3:3:2, and also supports inverse telecine. Pull-down techniques are only needed to remove
* artificial fields added when converting between 24 fps (film) and television fps (29.97 fps NTSC or 25 fps PAL).
*
* The <b>following graphic</b> displays a how frame rates are mapped, and how time remapping affects the order
* of frames returned from the FrameMapper.
* \image html /doc/images/FrameMapper.png
*
* Please see the following <b>Example Code</b>:
* \code
* // Create a frame mapper for a reader, and convert the frame rate (from 24 fps to 29.97 fps)
* FrameMapper mapping(reader, Fraction(30000, 1001), PULLDOWN_CLASSIC, 44100, 2, LAYOUT_STEREO);
* std::shared_ptr<Frame> frame2 = mapping.GetFrame(2);
* // If you need to change the mapping...
* mapping.ChangeMapping(Fraction(24, 1), PULLDOWN_CLASSIC, 48000, 2, LAYOUT_MONO)
* \endcode
*/
class FrameMapper : public ReaderBase {
private:
bool is_open;
bool field_toggle; // Internal odd / even toggle (used when building the mapping)
Fraction original; // The original frame rate
Fraction target; // The target frame rate
PulldownType pulldown; // The pull-down technique
ReaderBase *reader; // The source video reader
CacheMemory final_cache; // Cache of actual Frame objects
bool is_dirty; // When this is true, the next call to GetFrame will re-init the mapping
SWRCONTEXT *avr; // Audio resampling context object
// Internal methods used by init
void AddField(int64_t frame);
void AddField(Field field);
// Get Frame or Generate Blank Frame
std::shared_ptr<Frame> GetOrCreateFrame(int64_t number);
// Use the original and target frame rates and a pull-down technique to create
// a mapping between the original fields and frames or a video to a new frame rate.
// This might repeat or skip fields and frames of the original video, depending on
// whether the frame rate is increasing or decreasing.
void Init();
public:
// Init some containers
vector<Field> fields; // List of all fields
vector<MappedFrame> frames; // List of all frames
/// Default constructor for openshot::FrameMapper class
FrameMapper(ReaderBase *reader, Fraction target_fps, PulldownType target_pulldown, int target_sample_rate, int target_channels, ChannelLayout target_channel_layout);
/// Destructor
~FrameMapper();
/// Change frame rate or audio mapping details
void ChangeMapping(Fraction target_fps, PulldownType pulldown, int target_sample_rate, int target_channels, ChannelLayout target_channel_layout);
/// Close the openshot::FrameMapper and internal reader
void Close();
/// Get a frame based on the target frame rate and the new frame number of a frame
MappedFrame GetMappedFrame(int64_t TargetFrameNumber);
/// Get the cache object used by this reader
CacheMemory* GetCache() { return &final_cache; };
/// @brief This method is required for all derived classes of ReaderBase, and return the
/// openshot::Frame object, which contains the image and audio information for that
/// frame of video.
///
/// @returns The requested frame of video
/// @param requested_frame The frame number that is requested.
std::shared_ptr<Frame> GetFrame(int64_t requested_frame);
/// Determine if reader is open or closed
bool IsOpen();
/// Return the type name of the class
string Name() { return "FrameMapper"; };
/// Get and Set JSON methods
string Json(); ///< Generate JSON string of this object
void SetJson(string value); ///< Load JSON string into this object
Json::Value JsonValue(); ///< Generate Json::JsonValue for this object
void SetJsonValue(Json::Value root); ///< Load Json::JsonValue into this object
/// Open the internal reader
void Open();
/// Print all of the original frames and which new frames they map to
void PrintMapping();
/// Get the current reader
ReaderBase* Reader();
/// Resample audio and map channels (if needed)
void ResampleMappedAudio(std::shared_ptr<Frame> frame, int64_t original_frame_number);
};
}
#endif
FFmpegUtilities.h
Header file for FFmpegUtilities.
Fraction.h
Header file for Fraction class.
openshot::Field::isOdd
bool isOdd
Definition: FrameMapper.h:76
openshot::Field::Field
Field(int64_t frame, bool isodd)
Definition: FrameMapper.h:80
openshot::Field::Field
Field()
Definition: FrameMapper.h:78
openshot::SampleRange::frame_end
int64_t frame_end
Definition: FrameMapper.h:98
openshot
This namespace is the default namespace for all code in the openshot library.
Definition: AudioBufferSource.h:45
openshot::Fraction
This class represents a fraction.
Definition: Fraction.h:42
openshot::Field
This struct holds a single field (half a frame).
Definition: FrameMapper.h:73
openshot::FrameMapper::Name
string Name()
Return the type name of the class.
Definition: FrameMapper.h:199
openshot::Frame
This class represents a single frame of video (i.e. image & audio data)
Definition: Frame.h:115
KeyFrame.h
Header file for the Keyframe class.
openshot::SampleRange::sample_start
int sample_start
Definition: FrameMapper.h:96
openshot::MappedFrame::Even
Field Even
Definition: FrameMapper.h:113
openshot::SampleRange::frame_start
int64_t frame_start
Definition: FrameMapper.h:95
openshot::CacheMemory
This class is a memory-based cache manager for Frame objects.
Definition: CacheMemory.h:48
openshot::MappedFrame::Odd
Field Odd
Definition: FrameMapper.h:112
CacheMemory.h
Header file for CacheMemory class.
openshot::MappedFrame::Samples
SampleRange Samples
Definition: FrameMapper.h:114
openshot::MappedFrame
This struct holds two fields which together make up a complete video frame.
Definition: FrameMapper.h:110
SWRCONTEXT
#define SWRCONTEXT
Definition: FFmpegUtilities.h:132
openshot::SampleRange
This struct holds a the range of samples needed by this frame.
Definition: FrameMapper.h:93
Frame.h
Header file for Frame class.
openshot::SampleRange::total
int total
Definition: FrameMapper.h:101
openshot::FrameMapper
This class creates a mapping between 2 different frame rates, applying a specific pull-down technique...
Definition: FrameMapper.h:139
openshot::PULLDOWN_ADVANCED
@ PULLDOWN_ADVANCED
Advanced 2:3:3:2 pull-down (minimal dirty frames)
Definition: FrameMapper.h:63
ReaderBase.h
Header file for ReaderBase class.
openshot::SampleRange::sample_end
int sample_end
Definition: FrameMapper.h:99
OpenMPUtilities.h
Header file for OpenMPUtilities (set some common macros)
openshot::ReaderBase
This abstract class is the base class, used by all readers in libopenshot.
Definition: ReaderBase.h:96
openshot::PulldownType
PulldownType
This enumeration determines how frame rates are increased or decreased.
Definition: FrameMapper.h:60
openshot::FrameMapper::frames
vector< MappedFrame > frames
Definition: FrameMapper.h:167
openshot::ChannelLayout
ChannelLayout
This enumeration determines the audio channel layout (such as stereo, mono, 5 point surround,...
Definition: ChannelLayouts.h:43
openshot::FrameMapper::GetCache
CacheMemory * GetCache()
Get the cache object used by this reader.
Definition: FrameMapper.h:185
openshot::Field::Frame
int64_t Frame
Definition: FrameMapper.h:75
openshot::PULLDOWN_NONE
@ PULLDOWN_NONE
Do not apply pull-down techniques, just repeat or skip entire frames.
Definition: FrameMapper.h:64
openshot::FrameMapper::fields
vector< Field > fields
Definition: FrameMapper.h:166
Exceptions.h
Header file for all Exception classes.
openshot::PULLDOWN_CLASSIC
@ PULLDOWN_CLASSIC
Classic 2:3:2:3 pull-down.
Definition: FrameMapper.h:62