Krita/Filter API Discussion Notes

Cyrille and Dmitry were discussing changes for filter and data manager API at the February 2010 sprint.

Here are some conclusions:

Filter API changes

Filters should be applied to paint devices in place. It means that we will have something like KisFilter::process(KisPaintDeviceSP device, QRect applyRect, KisFilterConfiguration* kfc) instead of KisFilter::process(KisPaintDeviceSP src, KisPaintDeviceSP dst, QPoint srcOrigin, QPoint dstOrigin, QSize size, KisFilterConfiguration* kfc) (the last line is a bit simplified, just to show the meaning)

Why this change?

+ it allows us to use KisRectIterator inside filters that is much faster than any other iterators
+ we need one iterator only instead of two: one for destination and another one for source devices
- it needs some special api from KisDataManager (see below)

We don't need KisProcessingInformation anymore as we eliminated the use of two devices

Filter implementation do not need to worry about selections. KisFilter::process do not have selections anymore. All the selection painting should be done at the higher level. As a solution we decided to use some wrapper above KisFilter::process, e.g. KisFilter::process(KisPaintDeviceSP device, QRect applyRect, KisFilterConfiguration* kfc, KisSelectionSP selection) This function will be part of KisFilter api and need not to be overriden by implementation.

The wrapper above will rely on a special api from a KisDataManager. The latter will return the region of non-default pixels (actually this will be the list of non-default tiles). The filter will be applied to the rects from this list.

Still to be discussed: Usage of default pixel in KisSelection. Atm it is quite weird, so it can lower the use of regions to zero.

KisDataManager API changes

we need an opposite method to getMemento(). It will be called commit(). This method will fix the changes made during transaction onto the device.

Why this change?

KisTileDataPooler should know when to start preallocating tiles. Atm it works quite inefficient because new commits come right before getting new memento (and creating new transaction)

How this change?

KisTransaction will not inherit QUndoCommand anymore. KisTransactionData will do. KisTransaction will be only a wrapper for KisTransactionData and be stored in the stack (not heap) and will work like QMutexLocker.

QRegion KisDataManager::region() returns a region of non-default tiles. Works like extent() but returns QRegion instead of QRect.

void KisDataManager::bitBlt(KisDataManagerSP src, QPoint srcOrigin, QPoint dstOrigin, QSize size) This is a fast version of bitBlt that will explicitly share the tiles between data managers. Should be used by the KisPainter for cases when both color spaces coincide

KisDataManagerSP KisDataManager::fastClone(QRect regionOfInterest) This method will create a new data manager that resebles a source data manager on a rect AT LEAST as big as regionOfInteres. What does it mean? It means that the clone can be a bit larger than we asked in regionOfInterest. Why it is needed? For creating temporary devices during filtering or some other stuff.

The plan

Status	Description	Contact
DONE	KisDataManager::region()	Dmitry
TO DO	A wrapper for selections based on region() functionality	Cyrille	<{{{3}}}>
TO DO	Filters in-place application	Cyrille	<{{{3}}}>
TO DO	Remove KisProcessingInformation	Cyrille	<{{{3}}}>
DONE	Commit'able transactions	Dmitry
DONE	KisDataManager::bitBlt	Dmitry
DONE	KisDataManager::fastClone	Dmitry
TO DO	Connect KisPaintDevice::fastBitBlt to KisPainter	Cyrille	<{{{3}}}>