Infenro Home SDK Docs Blah

InfernoFilter

Declared in:/boot/home/devel/Inferno-project/Inferno/SDK/Headers/Plugins/InfernoFilter.h
Author: YNOP
Version:1.0
Date: Feb 5 2000
Summary:more...


A Inferno Filter Plugins provides a flexable way to impiment filters in a quick and painless manner. This class provides a abstraction layer between the document, user settings, GUI, and other parts of Inferno core which allow you to only have to deal with the basic filter impimentation.

Combinded with the BAC (Bitmap Accessor Class) filters are relativly painless and quick to write.

The Filter(...) method provides you direct access to a Inferno Layer which you can directly modify by accessing its GetData() method.

Here are some general filter catagories I suggest you use one of them, however if you feel you want to make up your own feel free - that works too. If yo don't export this then your filter will go into the General catagory.

Code like this should be inside of your .cpp file to spesify the filter catagory.

By adding a Sub Catagory you can spesify where in the Catagory list this is displayed. Seperators are put between each Sub catagory to give the use a visual cue. After that items are sorta by alpha name.

    FILTER_SYMBOLS char   FILTER_CATAGORY[] = BLUR_CATAGORY; 
    FILTER_SYMBOLS uint32 FILTER_SUBCATAGORY   = 0; 


Note that the Sub catagory is overridable via the INFERNO_FILTER_POSITION_ATTR attribute tag to the filter file itself (saved as a uint32) If this attribute exists it overrides the developer supplied subcatagory.

If you wish to add some comments you can via the description. You can add anything you wish... Just add this line to you cpp file this is a free form string so you can add chars like /n and /t

    FILTER_SYMBOLS char FILTER_DESCRIPTION[] = ""; 


Some other info you can add to let people know about you and your filter

     
    FILTER_SYMBOLS char FILTER_AUTHOR[] =    ""; 
    FILTER_SYMBOLS char FILTER_EMAIL[] =     ""; 
    FILTER_SYMBOLS char FILTER_COPYRIGHT[] = ""; 
    FILTER_SYMBOLS char FILTER_VERSION[] =   ""; 


Te let the core know what types you can support (for better error checking)
    FILTER_SYMBOLS char LAYER_TYPES_SUPPORTED[] = "Bitmap,Mask"; 


or if you can support all layer types (unlikly for a filter :P) however this will be assumed if you do not specify a type and then type checking will be up to the filter to get it right .. and not crash Inferno (so please specify a type)

    FILTER_SYMBOLS char LAYER_TYPES_SUPPORTED[] = "*"; 


A normal fitler wiht GUI will look somethign like this:


If the [ PROOF ] button is clicked, the filter will be applied in proof-mode. This means it will be rendered to the canvas, using I_PROOF_LOW_QUALITY as proof_quality parameter. The output is not final, as it will not affect the original image and the image will be restored on canceling the filter. Clicking [ OK ] wil run the filter with I_PROOF_HIGH_QUALITY, and the output will occure using the pop-up menu you see on the left bottom of the filter window.

The pop-up menu defines how the filter should handle selections and whether the output is placed on the current layer, or a new layer needs to be created for the output. A filter can use the filter_mode structure to know how it is applied.

    // this will change probably 
    struct filter_mode{ 
       BRect BoundingBox; 
       BBitmap *selection; 
       bool useSelection; 
    }; 


The bool useSelection reflects the usage of selection area or not. If it is true, the filter should take in account the current selection. To avoid having to scan the whole image on filtering, while just a small part is selected, the BRect BoundingBox holds the bounds of the current selection. If useSelection is false, the BoundingBox holds the bounds of the whole layer. If a filter does not have a GUI, the settings in the preferences are used to set the filter_mode.

The BBitmap *selection is a 8bit bitmap that holds a mask map for all pixels. If a pixel on the selection bitmap is set to 255, it is not part of the selection. Other values are in the selection, and can be other than 0 to reflect soft-selections. You do not have to use the selection-bitmap at all if you use the Bitmap Tools. Only thing you have to do is pass the useSelection bool to a specific draw function, and the Bitmap Tools handle the selection for you. It also handles the use of channels.

You can download the sample-sources to examine the use of the various methods. It has three frames for common filters.

Default - is a framework for a simple one pass filter without GUI Default with GUI - is a framework of a filter which uses a GUI. It has no thumbnail preview on it. Default with GUI and Thumbnail - Shows how you can add a thumbnail preview to your GUI using the Bitmap Tools. It uses multi- threading to keep the interfacing smooth.

Also in the SDK are two filters that were converted from The Gimp. The well known page-curl filter and a Charcoal filter. These are examples on how you can use the filterAPI together with the Bitmap Tools.



Hook Functions

SaveState()
GetSettingsView()
Filter()
Perform()

InfernoFilter()
InfernoFilter(BMessage *prefs,InfernoCommon *IC,bool CanDoProof = false)

Creates a new addon, and inits the Inferno Common object and sets proffing true/false

The instantiate_filter() Hook does not take in a bool for cdp, this is something you set to true/false in your constructor.



    InfernoFilter *instantiate_filter(BMessage *prefs,InfernoCommon *IC) {
       return new MyFilter(prefs,IC);
    }
    MyFilter::MyFilter(BMessage *prefs,InfernoCommon *IC):InfernoFilter(prefs,IC,true){
       ...
    }


Future cores may provide a Symbole instead of this paramater, however this works now so we haven't changed it


~InfernoFilter()
~InfernoFilter()

SaveState()
void SaveState(BMessage *prefs)

GetSettingsView()
BView* GetSettingsView()

Gives you a way to return a configuaration view for your filter. If you return NULL then we assume that the filter needs no user interaction and runs useing the default mode.


Filter()
status_t Filter(InfernoLayer *ILay, filter_mode fm, proof_quality quality)

Implemented by plugin to preform the actaull filtering of ILay passed in. The fm provides access to the selection data. You can use this directly (in casses of non bitmap layers or impimentation of your won selection checking code) or by passing it off to the BAC.

Currently only I_PROOF_HIGH_QUALITY is uses for all Filter calls. This may be extended in the future.

Always check the Layers type befor trying to access it via code like the following:


    if(strcmp(ILay->GetType(),"Bitmap") != 0){
       return B_ERROR;
    }else{
       bitmap_layer_info *bli = (bitmap_layer_info*)ILay->GetData();
       ...
    }
Failure to do this will most likely cause a crash in Inferno. Future cores may allow you to export supported types so that the core may do typ checking for you. However if you can support multiple layer types (Bitmap,Vector,Text,etc) they you should still do Type checking.


Proof()
status_t Proof(proof_quality quality = I_PROOF_LOW_QUALITY)

gives you a way to call proof on yourself. This way you can do live updates when options are changed. Be carefull as some filters are CPU heavy and can slow the system if Poof is called to rapidly.


Thumb()
BBitmap* Thumb(int32 size)

Provides a way for you to access a thumbnail of the Layer your working with of any size. The BBitmap is owned by the Layer and should not be deleted.


Perform()
status_t Perform(perform_code d, void *arg)

Reserved for the Future



Class Constants
Name Description
COLOR_CATAGORY Oh the pritty colors
IMAGE_CATAGORY
GENERIC_CATAGORY Duh, if you just dont know
BLUR_CATAGORY Bbbbllureee.....
SHARPEN_CATAGORY SHARP
EFFECT_CATAGORY 3ph3kz
DISTORT_CATAGORY DiStOrTiOnS
ANALYZER_CATAGORY
NOISE_CATAGORY N.%$^O%^.@!(I%,.S#$*^E
RENDER_CATAGORY
TEXTURE_CATAGORY
SKETCH_CATAGORY
VIDEO_CATAGORY
STYLIZE_CATAGORY
OTHER_CATAGORY
INFERNO_FILTER_POSITION_ATTR uint32 attribut discribing sub menu user position

Infenro Home SDK Docs Blah

Generated on 12/27/2001
Copyright © 1999-2001 Inferno Dev Team. All rights reserved.