PCL
pcl::ProcessImplementation Class Reference

Implementation of a PixInsight process instance. More...

#include <ProcessImplementation.h>

Public Member Functions

 ProcessImplementation (const MetaProcess *m)
 
 ProcessImplementation (const ProcessImplementation &)=default
 
virtual ~ProcessImplementation ()
 
virtual void AfterExecution (View &view)
 
virtual void AfterGlobalExecution ()
 
virtual void AfterReading ()
 
virtual void AfterWriting () const
 
virtual bool AllocateParameter (size_type sizeOrLength, const MetaParameter *p, size_type tableRow)
 
virtual void Assign (const ProcessImplementation &instance)
 
virtual bool BeforeExecution (View &view)
 
virtual bool BeforeGlobalExecution ()
 
virtual bool BeforeReading ()
 
virtual bool BeforeWriting () const
 
virtual bool CanExecuteGlobal (String &whyNot) const
 
virtual bool CanExecuteOn (const ImageVariant &image, String &whyNot) const
 
virtual bool CanExecuteOn (const View &view, String &whyNot) const
 
virtual bool ExecuteGlobal ()
 
virtual bool ExecuteOn (ImageVariant &image, const IsoString &hints)
 
virtual bool ExecuteOn (View &view)
 
virtual void Initialize ()
 
virtual bool IsHistoryUpdater (const View &view) const
 
virtual bool IsMaskable (const View &view, const ImageWindow &mask) const
 
virtual bool IsValidInterface (const ProcessInterface *i) const
 
void Launch () const
 
void LaunchGlobal () const
 
void LaunchInterface () const
 
void LaunchOn (ImageWindow &) const
 
void LaunchOn (View &) const
 
void LaunchOnCurrentView () const
 
void LaunchOnCurrentWindow () const
 
virtual void * LockParameter (const MetaParameter *p, size_type tableRow)
 
const MetaProcessMeta () const
 
virtual size_type ParameterLength (const MetaParameter *p, size_type tableRow) const
 
virtual ProcessInterfaceSelectInterface () const
 
virtual UndoFlags UndoMode (const View &view) const
 
virtual void UnlockParameter (const MetaParameter *p, size_type tableRow)
 
virtual bool Validate (String &info)
 
virtual bool ValidateParameter (void *value, const MetaParameter *p, size_type tableRow) const
 
uint32 Version () const
 

Detailed Description

Process instances are the main actors in the PixInsight environment, since they are responsible for all of the actual processing work. For example, process instances can be executed on views, on images and on the global context, edited through process interfaces, parsed by script interpreters, stored in processing histories and process containers, and managed as process icons and projects that can be transferred to and from special disk files (XPSM and XOSM formats).

In the PixInsight/PCL framework, a process class is formally defined as a descendant of the MetaProcess class, along with several descendants of MetaParameter classes. ProcessImplementation defines the behavior and functionality of an instance of a process class.

See also
MetaProcess, MetaParameter

Definition at line 96 of file ProcessImplementation.h.

Constructor & Destructor Documentation

◆ ProcessImplementation() [1/2]

pcl::ProcessImplementation::ProcessImplementation ( const MetaProcess m)
inline

Constructs a process instance.

Parameters
mPointer to a metaprocess that identifies the process class that this process instance belongs to.

Definition at line 106 of file ProcessImplementation.h.

◆ ProcessImplementation() [2/2]

pcl::ProcessImplementation::ProcessImplementation ( const ProcessImplementation )
default

Copy constructor.

◆ ~ProcessImplementation()

virtual pcl::ProcessImplementation::~ProcessImplementation ( )
inlinevirtual

Virtual destructor.

Definition at line 119 of file ProcessImplementation.h.

Member Function Documentation

◆ AfterExecution()

virtual void pcl::ProcessImplementation::AfterExecution ( View view)
inlinevirtual

This function is called just after execution of this process instance on the specified view.

ProcessImplementation instance classes rarely reimplement this function. It can be useful as a place to perform some cleanup work after execution.

When this function is invoked, the specified view has been completely processed. This includes a full history update (if appropriate), all involved notifications sent, and its screen rendition fully regenerated.

Definition at line 372 of file ProcessImplementation.h.

◆ AfterGlobalExecution()

virtual void pcl::ProcessImplementation::AfterGlobalExecution ( )
inlinevirtual

This function is called just after execution of this process instance in the global context.

ProcessImplementation instance classes rarely reimplement this function. It can be useful as a place to perform some cleanup work after execution.

Definition at line 528 of file ProcessImplementation.h.

◆ AfterReading()

virtual void pcl::ProcessImplementation::AfterReading ( )
inlinevirtual

This function is called just after this process instance has been read from an input stream, as a disk file.

You usually should need a reimplementation of this function if you also reimplemented BeforeReading(). Read the documentation for that member function for more information.

Note
The default implementation of this function does nothing.

Definition at line 606 of file ProcessImplementation.h.

◆ AfterWriting()

virtual void pcl::ProcessImplementation::AfterWriting ( ) const
inlinevirtual

This function is called just after this process instance has been written to an output stream, as a disk file.

You usually should need a reimplementation of this function if you also reimplemented BeforeWriting(). Read the documentation for that member function for more information.

Note
The default implementation of this function does nothing.

Definition at line 642 of file ProcessImplementation.h.

◆ AllocateParameter()

virtual bool pcl::ProcessImplementation::AllocateParameter ( size_type  sizeOrLength,
const MetaParameter p,
size_type  tableRow 
)
virtual

Allocates the required space to store a variable-length parameter value of the specified length or size. Returns true if the necessary space was successfully allocated.

Parameters
sizeOrLengthRequested size in bytes or length in elements of the parameter value being allocated.
pThe address of a metaparameter that identifies the variable-length parameter being allocated.
tableRowThe index of a table row where the requested parameter is defined. For parameters not belonging to tables, this parameter must be ignored.

For table parameters, sizeOrLength is a row count. For a string parameter, sizeOrLength is a string length in characters. For a block parameter, sizeOrLength is a block size in bytes.

Note
Reimplementing this function is mandatory for processes defining variable-length parameters.

◆ Assign()

virtual void pcl::ProcessImplementation::Assign ( const ProcessImplementation instance)
virtual

Assigns an existing instance to this object.

The PixInsight core application calls this function each time a process instance has to be replaced with a copy of another existing instance. This happens under a wide variety of situations. A good example is copying a process icon by dragging it to another icon. Another, less visible example is when a view's processing history is being copied as the initial processing of a duplicate view.

Assignment only occurs for assignable processes. A process is assignable unless its defining MetaProcess descendant class reimplements the MetaProcess::IsAssignable() member function to return false.

Assignable process instance implementation classes must reimplement this function, or a runtime exception will be thrown. This means that virtually all descendants classes of ProcessImplementation must reimplement this function. A plausible reason to define a non-assignable process (perhaps the only one) is because its instances have no data at all that could be assigned - an example is the standard Invert process.

◆ BeforeExecution()

virtual bool pcl::ProcessImplementation::BeforeExecution ( View view)
inlinevirtual

This function is called just before execution of this process instance on the specified view. Returns true if execution can continue.

This function is the last chance for a process instance to prevent execution on a particular view.

For example, a process that destroys the previews defined in the image window of a target view should always ask the user if it is OK to do so before execution. In this case, this function would be reimplemented to open a standard yes/no message box asking something like "About to destroy all previews in this image window. Are you sure?" to the user. False should be returned if the user answered "No".

Note
The default implementation of this function returns true, so by default execution on views is not stopped by this function.

Definition at line 335 of file ProcessImplementation.h.

◆ BeforeGlobalExecution()

virtual bool pcl::ProcessImplementation::BeforeGlobalExecution ( )
inlinevirtual

This function is called just before execution of this process instance in the global context. Returns true if global execution can continue.

This function is the last chance for a process instance to cancel execution in the global context. Reimplement it if you need to do something that the user should be aware of before global execution, giving her an opportunity to stop this process.

Note
The default implementation of this function returns true, so by default global execution is not stopped by this function.

Definition at line 495 of file ProcessImplementation.h.

◆ BeforeReading()

virtual bool pcl::ProcessImplementation::BeforeReading ( )
inlinevirtual

This function is called just before reading this process instance from an input stream, as a disk file. Returns true if the reading procedure can continue.

This function is not intended to allow or disallow instance reading operations based on source data contents. For that reason, this function doesn't receive a reference to the input stream from which this instance is about to be read.

The purpose of this function is preparing process instances to receive new parameters. This allows for a high degree of optimization in the implementation of actual parameter data and their acquisition.

Note
The default implementation of this function returns true, so by default instance reading is not stopped by this function.

Definition at line 591 of file ProcessImplementation.h.

◆ BeforeWriting()

virtual bool pcl::ProcessImplementation::BeforeWriting ( ) const
inlinevirtual

This function is called just before writing this process instance to an output stream, as a disk file. Returns true if the writing procedure can continue.

This function is not intended to allow or disallow instance writing operations based on target stream contents or properties. For that reason, this function doesn't receive a reference to the output stream to which this instance is about to be written.

The purpose of this function is preparing process instances to export their parameters. This allows for a high degree of optimization in the implementation of actual parameter data and their availability.

Note
The default implementation of this function returns true, so by default instance writing is not stopped by this function.

Definition at line 627 of file ProcessImplementation.h.

◆ CanExecuteGlobal()

virtual bool pcl::ProcessImplementation::CanExecuteGlobal ( String whyNot) const
virtual

Returns true iff this process instance could be successfully executed in the global context.

Parameters
[out]whyNotIf this function returns false, it should return also a brief text (256 characters maximum) in this string, explaining why this instance couldn't be executed in the global context.

Execution in the global context occurs when a process instance is executed without any specific target view. In such cases we say that a global process is being executed.

A good example of a pure global process is the GlobalPreferences process. This process allows the user modifying a number of global application options, but it does not apply to any image.

Other processes can perform as global processes sometimes, depending on specific parameter values. An example is the RGBWorkingSpaceParameters process, which can be applied to change a view's RGB working space (RGBWS), or to set the parameters of the global RGBWS.

Processes willing to perform global execution, either on a regular basis or under specific circumstances, must reimplement this function.

Note
The default implementation of this function returns false and assigns a standard message to the whyNot string (something like "The xxx process cannot be executed in the global context"). So by default a process instance cannot be executed in the global context.

◆ CanExecuteOn() [1/2]

virtual bool pcl::ProcessImplementation::CanExecuteOn ( const ImageVariant image,
String whyNot 
) const
virtual

Returns true iff this process instance could be successfully executed on the passed image.

Parameters
imageReference to an ImageVariant object on which this process is being tested to validate execution.
[out]whyNotIf this function returns false, it should return also a brief text (256 characters maximum) in this string, explaining why this instance be executed on the passed image.

This function will only be called for processes able to be executed on standalone images, that is, for processes that reimplement the following member function:

bool MetaProcess::CanProcessImages() const

to return true. Note that the default implementation of the above function returns false, so a process cannot be executed on ImageVariant instances by default.

Don't confuse standalone image execution with view execution, which corresponds to the ExecuteOn( View& ) member function.

Note
The default implementation of this function returns true, so by default an instance of a process able to be executed on standalone images can be executed on any image.

◆ CanExecuteOn() [2/2]

virtual bool pcl::ProcessImplementation::CanExecuteOn ( const View view,
String whyNot 
) const
virtual

Returns true iff this process instance could be successfully executed on a given view.

Parameters
viewReference to a view on which this process is being tested to validate execution.
[out]whyNotIf this function returns false, it should return also a brief text (256 characters maximum) in this string, explaining why this instance cannot be executed on the passed view.

In general, among many other possible reasons, a process instance class should reimplement this function if:

  • It is a process that cannot be executed on views. In this case, the reimplementation of this function should always return false.
  • It cannot be executed on all views. For example, some processes can only be executed on main views, but not on previews. Or perhaps this process cannot be executed on color images, but only on grayscale images.
  • Some instances, perhaps depending on specific parameter values or user-selectable options, may have limitations or cannot be executed on some types of views or images.

If this function returns false, giving a brief description of the reasons in the whyNot string is not mandatory, but neglecting it is considered bad programming practice.

Note
The default implementation of this function returns true, so by default a process instance can be executed on any view.

◆ ExecuteGlobal()

virtual bool pcl::ProcessImplementation::ExecuteGlobal ( )
virtual

Global execution routine. Executes this process instance in the global context. Returns true if execution took place successfully; false in the event of error.

This function must be reimplemented in process instance classes that can be executed globally. By default, instances cannot be executed globally. To allow global execution, an instance class should reimplement the CanExecuteGlobal() member function.

Exceptions can be freely thrown from this function; they will be caught and handled automatically by core PCL routines. For this reason, reimplementations of this function rarely return false when an error occurs; they prefer throwing exceptions instead.

Note
The default implementation of this function throws a runtime exception. This has been done on purpose to recall you that this function must be reimplemented for processes with global execution capabilities.

◆ ExecuteOn() [1/2]

virtual bool pcl::ProcessImplementation::ExecuteOn ( ImageVariant image,
const IsoString hints 
)
virtual

Image execution routine. Executes this process instance on the specified target image. Returns true if execution was successful; false in the event of error.

Parameters
imageReference to an ImageVariant object that transports the image to be processed.
hintsA string containing a (possibly empty) list of hints intended to modify the way an image is processed. A process can simply ignore all of these hints, or just look for one or more hints that it recognizes and supports, ignoring others. When two or more hints are specified, they must be separated by space characters (0x20). File formats also support hints in a similar way; see for example the FileFormatInstance::Open() member function for more information.

This function must be reimplemented by processes that can be executed on standalone images. To enable this functionality, the following member function:

bool MetaProcess::CanProcessImages() const

must be reimplemented to return true, since it returns false by default. Otherwise this function will never be called.

By default, an instance of a process able to be executed on standalone images is supposed to be executable on any image. To prevent image execution selectively, for example as a function of image properties, an instance class should reimplement:

bool ProcessImplementation::CanExecuteOn( const ImageVariant&, String& ) const

Exceptions can be freely thrown from this function; they will be caught and handled automatically by core PCL routines. For this reason, reimplementations of this function rarely return false when an error occurs; they prefer throwing exceptions instead.

Note
The default implementation of this function throws a runtime exception. This has been done on purpose to recall you that this function must be reimplemented for processes with image execution capabilities.

◆ ExecuteOn() [2/2]

virtual bool pcl::ProcessImplementation::ExecuteOn ( View view)
virtual

View execution routine. Executes this process instance on the specified target view. Returns true if execution took place successfully; false in the event of error.

This function must be reimplemented in process instance classes that can be executed on views. By default, all instances are supposed to be executable on views. To prevent view execution, an instance class should reimplement the CanExecuteOn() member function.

Exceptions can be freely thrown from this function; they will be caught and handled automatically by core PCL routines. For this reason, reimplementations of this function rarely return false when an error occurs; they prefer throwing exceptions instead.

Note
The default implementation of this function throws a runtime exception. This has been done on purpose to recall you that this function must be reimplemented for processes with view execution capabilities.

◆ Initialize()

virtual void pcl::ProcessImplementation::Initialize ( )
virtual

Initializes this process instance after construction. This is knwon as special initialization of process instances.

The PixInsight core application calls this function to initialize an instance just after it has been created by its class constructor.

There are cases where the entire initialization work required for a process instance cannot be accomplished in the instance class constructor (e.g., because it requires calling reimplemented virtual functions from a base class). In such cases, this function can be reimplemented to perform the pending initialization tasks immediately after instance construction.

This function is only called if the associated metaprocess class reimplements MetaProcess::NeedsInitialization() to return true.

◆ IsHistoryUpdater()

virtual bool pcl::ProcessImplementation::IsHistoryUpdater ( const View view) const
inlinevirtual

Returns true iff this process instance would require a history update for the specified view, if it was executed on it.

A history update would be required if this instance was modifying the view or its image in any way. By any way we mean not only changing pixel values, but to alter whatever property of the view or its image.

Note
The default implementation of this function returns true, so by default a process instance is supposed to update all views.

Definition at line 258 of file ProcessImplementation.h.

◆ IsMaskable()

virtual bool pcl::ProcessImplementation::IsMaskable ( const View view,
const ImageWindow mask 
) const
inlinevirtual

Returns true iff this is a maskable process instance for the specified view.

Parameters
viewReference to a view on which this process is being tested to validate maskable execution.
maskReference to an image window whose image would act as a mask after execution of this process instance.

A maskable instance is one whose resulting processed image can be masked. When a target image is masked after execution of a process instance, white mask pixels allow replacement of target pixels with fully processed values, and black mask pixels preserve original target pixel values. Gray mask pixel values yield proportional combinations of original and processed target pixels.

If a process cannot be masked, or if some process instances can't be masked sometimes, then this function should be reimplemented to return false, or an appropriate value depending on the execution context.

Note
The default implementation of this function returns true, so by default a process instance is supposed to be maskable for all views.

Definition at line 287 of file ProcessImplementation.h.

◆ IsValidInterface()

virtual bool pcl::ProcessImplementation::IsValidInterface ( const ProcessInterface i) const
inlinevirtual

Returns true iff the specified interface is a valid interface for this process instance.

This function is called when this instance is about to be imported by a process interface, to validate the import operation.

Note
This function is rarely reimplemented, for similar reasons to those exposed in the documentation for SelectInterface(). The default implementation of this function returns true if the specified interface is the same one that is returned by SelectInterface().

Definition at line 569 of file ProcessImplementation.h.

◆ Launch()

void pcl::ProcessImplementation::Launch ( ) const

Launches this process instance.

This function will lead to one of the following actions, in decreasing order of priority:

  • The SelectInterface() member function will be called for this instance. If the returned interface is valid, it will be activated and a copy of this instance will be imported.
  • If the MetaProcess::PrefersGlobalExecution() member function of the metaprocess associated to this instance returns true, or if no current view is available, a new thread will be created to execute this instance in the global context.
  • If the MetaProcess::PrefersGlobalExecution() member function of the metaprocess associated to this instance returns false, and there is a current view available, a new thread will be created to execute this instance on the current view.
  • A run-time exception will be thrown indicating that this instance cannot be executed.

◆ LaunchGlobal()

void pcl::ProcessImplementation::LaunchGlobal ( ) const

Execute this instance in the global context.

◆ LaunchInterface()

void pcl::ProcessImplementation::LaunchInterface ( ) const

Launches a process interface for this process instance.

The SelectInterface() member function will be called for this instance. The returned interface will be activated, and a copy of this instance will be imported.

◆ LaunchOn() [1/2]

void pcl::ProcessImplementation::LaunchOn ( ImageWindow ) const

Executes this instance on the main view of the specified image window.

◆ LaunchOn() [2/2]

void pcl::ProcessImplementation::LaunchOn ( View ) const

Executes this instance on the specified view.

◆ LaunchOnCurrentView()

void pcl::ProcessImplementation::LaunchOnCurrentView ( ) const

Executes this instance on the current view.

◆ LaunchOnCurrentWindow()

void pcl::ProcessImplementation::LaunchOnCurrentWindow ( ) const

Executes this instance in the current window or, more precisely, on its main view.

◆ LockParameter()

virtual void* pcl::ProcessImplementation::LockParameter ( const MetaParameter p,
size_type  tableRow 
)
virtual

Returns the fixed address of an actual parameter in this process instance, and locks it while the core application requires direct access to its data.

Parameters
pThe address of a metaparameter that identifies the parameter being locked.
tableRowThe index of a table row where the requested parameter is defined. For parameters not belonging to tables, this parameter must be ignored.

The PixInsight core application calls this function to get the actual address of a parameter in this process instance. The parameter should not be destroyed, changed or moved physically in memory until the UnlockParameter() member function is invoked for this instance with the same p and tableRow arguments.

Once UnlockParameter() has been called for a specific parameter, it can be freely moved, allocated or deallocated by this process instance.

Note
Reimplementing this function is mandatory for processes defining parameters.

◆ Meta()

const MetaProcess* pcl::ProcessImplementation::Meta ( ) const
inline

Returns a pointer to the metaprocess of this process instance.

The metaprocess defines the process class this instance belongs to.

Definition at line 128 of file ProcessImplementation.h.

◆ ParameterLength()

virtual size_type pcl::ProcessImplementation::ParameterLength ( const MetaParameter p,
size_type  tableRow 
) const
virtual

Returns the length or size of an actual variable-length parameter in this process instance.

Parameters
pThe address of a metaparameter that identifies the variable-length parameter.
tableRowThe index of a table row where the requested parameter is defined. For parameters not belonging to tables, this parameter must be ignored.

For tables, you must reimplement this function to return the current number of rows. For strings, you must return the string length in characters (not bytes). For blocks, you must return the size in bytes.

Note
Reimplementing this function is mandatory for processes defining variable-length parameters.

◆ SelectInterface()

virtual ProcessInterface* pcl::ProcessImplementation::SelectInterface ( ) const
inlinevirtual

Returns the address of an interface appropriate to edit this process instance. Returns zero if there is no available interface for this process instance.

This function is called when an existing instance is activated in the core application's GUI (e.g., by double-clicking a process icon). When the process is selected in a generic way (e.g., from the Process Explorer window), MetaProcess::DefaultInterface() is called instead.

This function must be reimplemented if multiple interfaces are available for this process class that are selectable on a per-instance basis.

Note
Reimplementing this function is very infrequent. This is because the default implementation just returns MetaProcess::DefaultInterface(), which is adequate for processes associated to a single interface, as are the majority of them.

Definition at line 551 of file ProcessImplementation.h.

◆ UndoMode()

virtual UndoFlags pcl::ProcessImplementation::UndoMode ( const View view) const
inlinevirtual

Returns a combination of flags indicating the required contents of a history update record for the specified view if this instance was executed on it.

The returned value is an OR'ed combination of flags that must be specified with the symbolic constants defined in the UndoFlag namespace.

When reimplementing this function, you should include flags for all data items that your process instances modify in target views. For example, if a process instance modifies the FITS header keywords of target images, the reimplementation of this function should include the UndoFlag::Keywords flag.

Note
The default implementation of this function returns UndoFlag::DefaultMode. This value selects a default set of items, including pixel data, that will be stored in a history record for the specified view before executing this process instance on it. You normally won't need to reimplement this function, since the default history data set is appropriate for most processes.

Definition at line 313 of file ProcessImplementation.h.

◆ UnlockParameter()

virtual void pcl::ProcessImplementation::UnlockParameter ( const MetaParameter p,
size_type  tableRow 
)
virtual

This function is called by the core application after LockParameter(), when direct access to an specified actual parameter is no longer needed.

Parameters
pThe address of a metaparameter that identifies the parameter being unlocked.
tableRowThe index of a table row where the requested parameter is defined. For parameters not belonging to tables, this parameter must be ignored.

When this function is invoked, the instance is free to move or change the parameter, until the next call to LockParameter() with the same p and tableRow arguments.

Note
This function is not called if the corresponding MetaParameter::NeedsUnlocking() member function has not been reimplemented to return true in the derived class that the specified parameter *p is an instance of.

◆ Validate()

virtual bool pcl::ProcessImplementation::Validate ( String info)
virtual

Returns true iff this process instance is currently valid for execution.

Parameters
[out]infoIf this function returns false, it should return also a brief text (256 characters maximum) in this string, describing why this is an invalid instance.

The PixInsight core application calls this function to validate an instance just before attempting to execute it, either on a view or in the global context.

This function is only called if the associated metaprocess class reimplements MetaProcess::NeedsValidation() to return true.

If this function returns false, giving a brief description of the reasons in the info string is not mandatory, although strongly recommended and considered good programming practice.

◆ ValidateParameter()

virtual bool pcl::ProcessImplementation::ValidateParameter ( void *  value,
const MetaParameter p,
size_type  tableRow 
) const
virtual

This function is called to validate a parameter value for an actual parameter in this process instance. Returns true if the specified value is a valid value for the specified parameter in this instance.

Parameters
valuePointer to the parameter value being tested.
pThe address of a metaparameter that identifies the parameter being validated.
tableRowThe index of a table row where the requested parameter is defined. For parameters not belonging to tables, this parameter must be ignored.
Note
This function is not called if the corresponding MetaParameter::NeedsValidation() member function has not been reimplemented to return true in the derived class that the specified parameter *p is an instance of.

◆ Version()

uint32 pcl::ProcessImplementation::Version ( ) const

Returns the version number of this process instance.

Instance version numbers are useful to manage different implementations of processes, especially when instances are deserialized from existing projects, process icons, etc.

This function may return zero if the version number is undefined for this instance for some reason, although this should not happen under normal conditions. Valid version numbers are always ≥ 1.

The version number that will be assigned to newly created process instances will always be the value returned by the MetaProcess::Version() member function (or a reimplementation of it) for the parent metaprocess.


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