Resamples an image to a given resolution. More...

#include <resampler.h>

Inheritance diagram for Beatmup::BitmapResampler:

Public Types
enum class	Mode { NEAREST_NEIGHBOR , BOX , LINEAR , CUBIC , CONVNET }
	Resampling mode (algorithm) specification. More...

Public Types inherited from Beatmup::AbstractTask
enum class	TaskDeviceRequirement { CPU_ONLY , GPU_OR_CPU , GPU_ONLY }
	Specifies which device (CPU and/or GPU) is used to run the task. More...

Public Member Functions
	BitmapResampler (Context &context)
	Creates a resampler. More...

	~BitmapResampler ()

void	setInput (AbstractBitmap *input)
	Sets the image to process. More...

void	setOutput (AbstractBitmap *output)
	Sets the output image. More...

AbstractBitmap *	getInput ()

AbstractBitmap *	getOutput ()

void	setMode (Mode mode)
	Sets the resampling algorithm to use. More...

Mode	getMode () const
	Returns currently selected resampling algorithm. More...

void	setCubicParameter (float alpha)
	Sets cubic interpolation parameter ("alpha"). More...

float	getCubicParameter () const
	Returns cubic interpolation parameter ("alpha"). More...

void	setUsingEs31IfAvailable (bool useEs31)
	Defines OpenGL ES backend selection policy (2.0 vs 3.1) when applicable. More...

void	setInputRect (const IntRectangle &rect)
	Specifies a rectangular working area in the input bitmap. More...

void	setOutputRect (const IntRectangle &rect)
	Specifies a rectangular working area in the output bitmap. More...

IntRectangle	getInputRect () const

IntRectangle	getOutputRect () const

Public Member Functions inherited from Beatmup::Object
virtual	~Object ()

Static Public Attributes
static const float	DEFAULT_CUBIC_PARAMETER = -0.5f

Protected Member Functions
virtual TaskDeviceRequirement	getUsedDevices () const
	Communicates devices (CPU and/or GPU) the task is run on. More...

virtual bool	process (TaskThread &thread)
	Executes the task on CPU within a given thread. More...

virtual bool	processOnGPU (GraphicPipeline &gpu, TaskThread &thread)
	Executes the task on GPU. More...

virtual void	beforeProcessing (ThreadIndex, ProcessingTarget target, GraphicPipeline *)
	Instruction called before the task is executed. More...

virtual void	afterProcessing (ThreadIndex, GraphicPipeline *, bool)
	Instruction called after the task is executed. More...

virtual ThreadIndex	getMaxThreads () const
	Gives the upper limint on the number of threads the task may be performed by. More...

Private Attributes
Context &	context
	a context managing intermediate bitmaps More...

AbstractBitmap *	input

AbstractBitmap *	output
	input and output bitmaps More...

IntRectangle	srcRect

IntRectangle	destRect

Mode	mode

float	cubicParameter

X2UpsamplingNetwork *	convnet
	convnet instance More...

bool	isUsingEs31IfAvailable
	if `true`, uses OpenGL ES 3.1 backend when available instead ES 2.0 More...

Additional Inherited Members
Static Public Member Functions inherited from Beatmup::AbstractTask
static ThreadIndex	validThreadCount (int number)
	Valid thread count from a given integer value. More...

Private Member Functions inherited from Beatmup::BitmapContentLock
	BitmapContentLock ()

	~BitmapContentLock ()

void	readLock (GraphicPipeline gpu, AbstractBitmap bitmap, ProcessingTarget target)
	Locks content of a bitmap for reading using a specific processing target device. More...

void	writeLock (GraphicPipeline gpu, AbstractBitmap bitmap, ProcessingTarget target)
	Locks content of a bitmap for writing using a specific processing target device. More...

void	unlock (AbstractBitmap *bitmap)
	Drops a lock to the bitmap. More...

void	unlockAll ()
	Unlocks all the locked bitmaps unconditionally. More...

template<const ProcessingTarget target>
void	lock (GraphicPipeline gpu, AbstractBitmap input, AbstractBitmap *output)

void	lock (GraphicPipeline gpu, ProcessingTarget target, AbstractBitmap input, AbstractBitmap *output)

template<const ProcessingTarget target>
void	lock (GraphicPipeline gpu, std::initializer_list< AbstractBitmap > read, std::initializer_list< AbstractBitmap * > write)

template<typename ... Args>
void	unlock (AbstractBitmap *first, Args ... others)

Detailed Description

Resamples an image to a given resolution.

Implements different resampling approaches, including standard ones (bilinear, bicubic, etc.) and a neural network-based 2x upsampling approach dubbed as "x2".

Definition at line 33 of file resampler.h.

Member Enumeration Documentation

◆ Mode

enum Beatmup::BitmapResampler::Mode

strong

Resampling mode (algorithm) specification.

Enumerator
NEAREST_NEIGHBOR	zero-order: usual nearest neighbor
BOX	"0.5-order": anti-aliasing box filter; identical to nearest neighbor when upsampling
LINEAR	first order: bilinear interpolation
CUBIC	third order: bicubic interpolation
CONVNET	upsampling x2 using a convolutional neural network

Definition at line 38 of file resampler.h.

                         {
             NEAREST_NEIGHBOR,    //!< zero-order: usual nearest neighbor
             BOX,                 //!< "0.5-order": anti-aliasing box filter; identical to nearest neighbor when upsampling
             LINEAR,              //!< first order: bilinear interpolation
             CUBIC,               //!< third order: bicubic interpolation
             CONVNET              //!< upsampling x2 using a convolutional neural network
         };

Constructor & Destructor Documentation

◆ BitmapResampler()

BitmapResampler::BitmapResampler ( Context & context )

Creates a resampler.

Parameters

context A context instance used to manage resources required to run some of resampling algorithms.

Definition at line 32 of file resampler.cpp.

                                                  :
     context(context),
     input(nullptr), output(nullptr), mode(Mode::CUBIC), cubicParameter(DEFAULT_CUBIC_PARAMETER), convnet(nullptr),
     isUsingEs31IfAvailable(false)
 {}

◆ ~BitmapResampler()

BitmapResampler::~BitmapResampler ( )

Definition at line 39 of file resampler.cpp.

                                   {
     if (convnet)
         delete convnet;
 }

Member Function Documentation

◆ getUsedDevices()

AbstractTask::TaskDeviceRequirement BitmapResampler::getUsedDevices ( ) const

protectedvirtual

Communicates devices (CPU and/or GPU) the task is run on.

Reimplemented from Beatmup::AbstractTask.

Definition at line 85 of file resampler.cpp.

                                                                         {
     return mode == Mode::CONVNET ? TaskDeviceRequirement::GPU_ONLY : TaskDeviceRequirement::CPU_ONLY;
 }

◆ process()

bool BitmapResampler::process ( TaskThread & thread )

protectedvirtual

Executes the task on CPU within a given thread.

Generally called by multiple threads.

Parameters

thread associated task execution context

Returns: true if the execution is finished correctly, false otherwise

Implements Beatmup::AbstractTask.

Definition at line 137 of file resampler.cpp.

                                                 {
     switch (mode) {
         case Mode::NEAREST_NEIGHBOR:
             BitmapProcessing::pipeline<Kernels::NearestNeighborResampling>(
                 *input, *output,
                 srcRect, destRect, thread
             );
             break;
  
         case Mode::BOX:
             BitmapProcessing::pipeline<Kernels::BoxResampling>(
                 *input, *output,
                 srcRect, destRect, thread
             );
             break;
  
         case Mode::LINEAR:
             BitmapProcessing::pipeline<Kernels::BilinearResampling>(
                 *input, *output,
                 srcRect, destRect, thread
             );
             break;
  
         case Mode::CUBIC:
             BitmapProcessing::pipeline<Kernels::BicubicResampling>(
                 *input, *output,
                 srcRect, destRect, cubicParameter, thread
             );
             break;
  
         case Mode::CONVNET:
             break;
  
         default:
             Insanity::insanity("Resampling mode not implemented");
     }
     return true;
 }

◆ processOnGPU()

bool BitmapResampler::processOnGPU	(	GraphicPipeline &	gpu,
		TaskThread &	thread
	)

protectedvirtual

Executes the task on GPU.

Parameters

gpu	graphic pipeline instance
thread	associated task execution context

Returns: true if the execution is finished correctly, false otherwise

Reimplemented from Beatmup::AbstractTask.

Definition at line 177 of file resampler.cpp.

                                                                            {
     switch (mode) {
         case Mode::CONVNET:
             convnet->process(gpu, *input, *output);
             break;
  
         default:
             Insanity::insanity("Resampling mode not implemented");
     }
     return true;
 }

◆ beforeProcessing()

void BitmapResampler::beforeProcessing	(	ThreadIndex	threadCount,
		ProcessingTarget	target,
		GraphicPipeline *	gpu
	)

protectedvirtual

Instruction called before the task is executed.

Parameters

threadCount	Number of threads used to perform the task
target	Device used to perform the task
gpu	A graphic pipeline instance; may be null.

Reimplemented from Beatmup::AbstractTask.

Definition at line 90 of file resampler.cpp.

                                                                                                              {
     NullTaskInput::check(input, "input bitmap");
     NullTaskInput::check(output, "output bitmap");
     RuntimeError::check(input != output, "input and output is the same bitmap");
     RuntimeError::check(
         srcRect == input->getSize().halfOpenedRectangle() && destRect == output->getSize().halfOpenedRectangle(),
         "input and output rectangular areas not matching the corresponding bitmaps are not supported when using GPU"
     );
     srcRect.normalize();
     srcRect.limit(IntRectangle(0, 0, input->getWidth(), input->getHeight()));
     destRect.normalize();
     destRect.limit(IntRectangle(0, 0, output->getWidth(), output->getHeight()));
  
     if (mode == Mode::CONVNET) {
         RuntimeError::check(gpu != nullptr, "convnet resampling requires GPU");
         RuntimeError::check(input->getContext() == context && output->getContext() == context,
             "input and/or output bitmaps contexts do not match the BitmapRecycler context");
         RuntimeError::check(
             destRect.width() == 2 * srcRect.width() && destRect.height() == 2 * srcRect.height(),
             "convnet resampling is only applicable for 2x upsampling"
         );
  
 #ifndef BEATMUP_OPENGLVERSION_GLES20
         // check if the ES backend needed to be upgraded to 3.1
         if (convnet && isUsingEs31IfAvailable && !convnet->usesEs31Backend()) {
             delete convnet;
             convnet = nullptr;
         }
 #endif
  
         // init convnet instance if not yet
 #ifndef BEATMUP_OPENGLVERSION_GLES20
         if (!convnet && isUsingEs31IfAvailable)
             convnet = new GLES31X2UpsamplingNetwork(context, *gpu);
 #endif
         if (!convnet)
             convnet = new GLES20X2UpsamplingNetwork(*context.getGpuRecycleBin(), *gpu);
     }
     lock(gpu, target, input, output);
 }

◆ afterProcessing()

void BitmapResampler::afterProcessing	(	ThreadIndex	threadCount,
		GraphicPipeline *	gpu,
		bool	aborted
	)

protectedvirtual

Instruction called after the task is executed.

Parameters

threadCount	Number of threads used to perform the task
gpu	GPU to be used to execute the task; may be null.
aborted	`true` if the task was aborted

Reimplemented from Beatmup::AbstractTask.

Definition at line 132 of file resampler.cpp.

                                                                                                  {
     unlock(input, output);
 }

◆ getMaxThreads()

ThreadIndex BitmapResampler::getMaxThreads ( ) const

protectedvirtual

Gives the upper limint on the number of threads the task may be performed by.

The actual number of threads running a specific task may be less or equal to the returned value, depending on the number of workers in ThreadPool running the task.

< minimum number of pixels per worker

Reimplemented from Beatmup::AbstractTask.

Definition at line 79 of file resampler.cpp.

                                                  {
     static const int MIN_PIXELS_PER_THREAD = 1000; //!< minimum number of pixels per worker
     return AbstractTask::validThreadCount(std::min(destRect.height() + 1, srcRect.getArea() / MIN_PIXELS_PER_THREAD));
 }

◆ setInput()

void BitmapResampler::setInput ( AbstractBitmap * input )

Sets the image to process.

Parameters

[in] input The input image

Definition at line 45 of file resampler.cpp.

                                                     {
     this->input = input;
     if (input)
         srcRect = IntRectangle(0, 0, input->getWidth(), input->getHeight());
 }

◆ setOutput()

void BitmapResampler::setOutput ( AbstractBitmap * output )

Sets the output image.

The output image contains the resampled version of the input one once the task finishes.

Parameters

[in] output The output image

Definition at line 51 of file resampler.cpp.

                                                       {
     this->output = output;
     if (output)
         destRect = IntRectangle(0, 0, output->getWidth(), output->getHeight());
 }

◆ getInput()

AbstractBitmap* Beatmup::BitmapResampler::getInput ( )

inline

Definition at line 86 of file resampler.h.

86 { return input; }

◆ getOutput()

AbstractBitmap* Beatmup::BitmapResampler::getOutput ( )

inline

Definition at line 87 of file resampler.h.

87 { return output; }

◆ setMode()

void BitmapResampler::setMode ( Mode mode )

Sets the resampling algorithm to use.

Parameters

[in] mode The algorithm to use

Definition at line 59 of file resampler.cpp.

                                        {
     this->mode = mode;
 }

◆ getMode()

Mode Beatmup::BitmapResampler::getMode ( ) const

inline

Returns currently selected resampling algorithm.

Definition at line 98 of file resampler.h.

98 { return mode; }

◆ setCubicParameter()

void BitmapResampler::setCubicParameter ( float alpha )

Sets cubic interpolation parameter ("alpha").

Has no impact if the resampling mode is different from cubic.

Parameters

[in] alpha The alpha parameter value

Definition at line 64 of file resampler.cpp.

                                                    {
     cubicParameter = alpha;
 }

◆ getCubicParameter()

float Beatmup::BitmapResampler::getCubicParameter ( ) const

inline

Returns cubic interpolation parameter ("alpha").

Definition at line 110 of file resampler.h.

110 { return cubicParameter; }

◆ setUsingEs31IfAvailable()

void Beatmup::BitmapResampler::setUsingEs31IfAvailable ( bool useEs31 )

inline

Defines OpenGL ES backend selection policy (2.0 vs 3.1) when applicable.

Parameters

[in] useEs31 If true, ES 3.1 backend will be used when available, otherwise ES 2.0 is used.

Definition at line 116 of file resampler.h.

116 { isUsingEs31IfAvailable = useEs31; }

◆ setInputRect()

void BitmapResampler::setInputRect ( const IntRectangle & rect )

Specifies a rectangular working area in the input bitmap.

Pixels outside of this area are not used.

Definition at line 69 of file resampler.cpp.

                                                            {
     srcRect = rect;
 }

◆ setOutputRect()

void BitmapResampler::setOutputRect ( const IntRectangle & rect )

Specifies a rectangular working area in the output bitmap.

Pixels outside of this area are not affected.

Definition at line 74 of file resampler.cpp.

                                                             {
     destRect = rect;
 }

◆ getInputRect()

IntRectangle Beatmup::BitmapResampler::getInputRect ( ) const

inline

Definition at line 130 of file resampler.h.

130 { return srcRect; }

◆ getOutputRect()

IntRectangle Beatmup::BitmapResampler::getOutputRect ( ) const

inline

Definition at line 131 of file resampler.h.

131 { return destRect; }

Member Data Documentation

◆ context

Context& Beatmup::BitmapResampler::context

private

a context managing intermediate bitmaps

Definition at line 46 of file resampler.h.

◆ input

AbstractBitmap* Beatmup::BitmapResampler::input

private

Definition at line 47 of file resampler.h.

◆ output

AbstractBitmap * Beatmup::BitmapResampler::output

private

input and output bitmaps

Definition at line 47 of file resampler.h.

◆ srcRect

IntRectangle Beatmup::BitmapResampler::srcRect

private

Definition at line 48 of file resampler.h.

◆ destRect

IntRectangle Beatmup::BitmapResampler::destRect

private

Definition at line 48 of file resampler.h.

◆ mode

Mode Beatmup::BitmapResampler::mode

private

Definition at line 49 of file resampler.h.

◆ cubicParameter

float Beatmup::BitmapResampler::cubicParameter

private

Definition at line 50 of file resampler.h.

◆ convnet

X2UpsamplingNetwork* Beatmup::BitmapResampler::convnet

private

convnet instance

Definition at line 51 of file resampler.h.

◆ isUsingEs31IfAvailable

bool Beatmup::BitmapResampler::isUsingEs31IfAvailable

private

if true, uses OpenGL ES 3.1 backend when available instead ES 2.0

Definition at line 52 of file resampler.h.

◆ DEFAULT_CUBIC_PARAMETER

const float BitmapResampler::DEFAULT_CUBIC_PARAMETER = -0.5f

static

Definition at line 63 of file resampler.h.

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

core/bitmap/resampler.h
core/bitmap/resampler.cpp

Public Types

Public Member Functions

Static Public Attributes

Protected Member Functions

Private Attributes

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

◆ Mode

Constructor & Destructor Documentation

◆ BitmapResampler()

◆ ~BitmapResampler()

Member Function Documentation

◆ getUsedDevices()

◆ process()

◆ processOnGPU()

◆ beforeProcessing()

◆ afterProcessing()

◆ getMaxThreads()

◆ setInput()

◆ setOutput()

◆ getInput()

◆ getOutput()

◆ setMode()

◆ getMode()

◆ setCubicParameter()

◆ getCubicParameter()

◆ setUsingEs31IfAvailable()

◆ setInputRect()

◆ setOutputRect()

◆ getInputRect()

◆ getOutputRect()

Member Data Documentation

◆ context

◆ input

◆ output

◆ srcRect

◆ destRect

◆ mode

◆ cubicParameter

◆ convnet

◆ isUsingEs31IfAvailable

◆ DEFAULT_CUBIC_PARAMETER