📄 extending the api.htm
字号:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<!-- saved from url=(0094)http://java.sun.com/products/java-media/jai/forDevelopers/jai1_0_1guide-unc/Extension.doc.html -->
<HTML><HEAD><TITLE>Extending the API</TITLE>
<META http-equiv=Content-Type content="text/html; charset=gb2312">
<META content=exclude name=collection>
<META content="MSHTML 6.00.2900.3132" name=GENERATOR></HEAD>
<BODY bgColor=#ffffff>
<CENTER><A
href="http://java.sun.com/products/java-media/jai/forDevelopers/jai1_0_1guide-unc/JAITOC.fm.html"><IMG
alt=Contents src="Extending the API.files/contents.gif"></A> <A
href="http://java.sun.com/products/java-media/jai/forDevelopers/jai1_0_1guide-unc/Encode.doc.html"><IMG
alt=Previous src="Extending the API.files/previous.gif"></A> <A
href="http://java.sun.com/products/java-media/jai/forDevelopers/jai1_0_1guide-unc/Examples.doc.html"><IMG
alt=Next src="Extending the API.files/next.gif"></A>
<P><FONT size=5><I>Programming in Java Advanced Imaging</I></FONT> </CENTER><BR>
<CENTER><A name=47227>
<TABLE width="90%" border=0>
<TBODY>
<TR>
<TD align=right><FONT size=3>C H A P T E R</FONT><FONT size=7><IMG
src="Extending the API.files/sm-space.gif">14</FONT></TD></TR></TBODY></TABLE></A></CENTER>
<CENTER><A name=47285>
<TABLE width="90%" border=0>
<TBODY>
<TR>
<TD align=right>
<HR noShade SIZE=7>
<FONT size=6>Extending the API</FONT></TD></TR></TBODY></TABLE></A></CENTER>
<BLOCKQUOTE>
<P><BR><BR><BR>
<P><FONT size=7><B>T</B></FONT>HIS chapter describes how the JAI API may be
extended.
<P><A name=51567>
<H2>14.1 <IMG src="Extending the API.files/space.gif">Introduction</H2></A>No
image processing API can hope to capture the enormous variety of operations
that can be performed on a digital image. Although the JAI API supports a
large number of imaging operations, it was designed from the beginning to
encourage programmers to write extensions rather than manipulating image data
directly. JAI allows virtually <EM>any</EM> image processing algorithm to be
added to the API and used as if it were a native part of the API.
<P>The mechanism for adding functionality to the API can be presented at
multiple levels of encapsulation and complexity. This allows programmers who
wish to add simple things to the API to deal with simple concepts, while more
complex extensions have complete control over their environment at the lowest
levels of abstraction. The API also supports a variety of programming styles,
including an immediate mode and a deferred mode of execution for different
types of imaging applications.
<P><A name=55405>
<H2>14.2 <IMG src="Extending the API.files/space.gif">Package Naming
Convention</H2></A>All extensions to JAI require the addition of new classes.
All new classes are grouped into packages as a convenient means of organizing
the new classes and separating the new classes from code libraries provided by
others.
<P>All new packages are given a <EM>product name</EM>. A product name is the
accepted Java method of using your company's reversed Internet address to name
new packages. This product naming convention helps to guarantee the uniqueness
of package names. Supposing that your company's Internet address is
<CODE>WebStuff.COM</CODE> and you wish to create a new package named
<CODE>Prewitt</CODE>. A good choice of package name would be
<P><PRE> com.webstuff.Prewitt
</PRE>Or, even
<P><PRE> com.webstuff.media.jai.Prewitt
</PRE>To uniquely identify the package as part of JAI.
<P>The above new <CODE>prewitt</CODE> class file must now be placed into a
subdirectory that matches the product name, such as:
<P>
<DL><A name=55468>
<DT>
<DD><CODE>com/webstuff/media/jai</CODE> <EM>for Solaris-based systems</EM>
</A>
<P>
<DL><A name=55482>
<DT>
<DD>or </A>
<P></P></DD></DL><A name=55477>
<DT>
<DD><CODE>com\webstuff\media\jai</CODE> <EM>for Windows systems</EM> </A>
<P></P></DD></DL>The Java convention for class naming is to use initial caps
for the name, as in the <CODE>Prewitt</CODE> example above. So called
multi-word class names use initial caps for each word. For example
<CODE>AddOpImage</CODE>.
<P>Vendors are encouraged to use unique product names (by means of the Java
programming language convention of reversed internet addresses) to maximize
the likelihood of a clean installation.
<P><A name=50856>
<H2>14.3 <IMG src="Extending the API.files/space.gif">Writing New
Operators</H2></A>To extend the JAI API by creating new operations, you will
need to write a new <CODE>OpImage</CODE> subclass. This may be done by
subclassing one or more existing utility classes to automate some of the
details of the operator you wish to implement. For most operators, you need
only supply a routine that is capable of producing an arbitrary rectangle of
output, given contiguous source data.
<P>Once created, new operators may be made available to users transparently
and without user source code changes using the JAI registry mechanism.
Existing applications may be tuned for new hardware platforms by strategic
insertion of new implementations of existing operators.
<P>To create a new operator, you need to create the following new classes:
<P>
<UL>
<LI>A class that extends the <CODE>OpImage</CODE> class or any of its
subclasses. This new class does the actual processing. See <A
href="http://java.sun.com/products/java-media/jai/forDevelopers/jai1_0_1guide-unc/Extension.doc.html#51621">Section
14.3.1, "Extending the OpImage Class</A>."
<P></P></LI></UL>
<UL>
<LI>A class that extends the <CODE>OperationDescriptor</CODE> class. This
new class describes the operation such as name, parameter list, and so on.
See <A
href="http://java.sun.com/products/java-media/jai/forDevelopers/jai1_0_1guide-unc/Extension.doc.html#51155">Section
14.3.2, "Extending the OperationDescriptor Interface</A>."
<P></P></LI></UL>
<UL>
<LI>If the operator will function in the Rendered mode only, a class that
implements <CODE>java.awt.image.renderable.RenderedImageFactory</CODE>.
<P></P></LI></UL><A name=51621>
<H3>14.3.1 <IMG src="Extending the API.files/space.gif">Extending the OpImage
Class</H3></A>Every new operator being written must be a subclass of
<CODE>OpImage</CODE> or one of its subclasses. The <CODE>OpImage</CODE> class
currently has the following subclasses:
<P>
<TABLE cellPadding=3 border=3>
<CAPTION><FONT size=-1><B><A name=51670><I>Table 14-1 </I><IMG
src="Extending the API.files/sm-blank.gif" border=0> OpImage Subclasses
</A></B></FONT></CAPTION>
<TBODY>
<TR vAlign=top>
<TH><A name=51674>Class </A>
<TH><A name=51676>Description </A>
<TR vAlign=top>
<TD><A name=51678>AreaOpImage</A><BR>
<TD><A name=51702>An abstract base class for image operators that
require only a fixed rectangular source region around a source pixel in
order to compute each destination pixel.</A><BR>
<TR vAlign=top>
<TD><A name=55534>NullOpImage</A><BR>
<TD><A name=55536>Extends: PointOpImage</A><BR><A name=55537>A trivial
OpImage subclass that simply transmits its source unchanged. Potentially
useful when an interface requires an OpImage but another sort of
RenderedImage (such as a TiledImage) is to be used.</A><BR>
<TR vAlign=top>
<TD><A name=51690>PointOpImage</A><BR>
<TD><A name=51723>An abstract base class for image operators that
require only a single source pixel in order to compute each destination
pixel.</A><BR>
<TR vAlign=top>
<TD><A name=55550>ScaleOpImage</A><BR>
<TD><A name=55552>Extends: WarpOpImage</A><BR><A name=55553>An abstract
base class for scale-like operations that require rectilinear backwards
mapping and padding by the resampling filter dimensions.</A><BR>
<TR vAlign=top>
<TD><A name=51781>SourcelessOpImage</A><BR>
<TD><A name=51783>An abstract base class for image operators that have
no image sources.</A><BR>
<TR vAlign=top>
<TD><A name=51849>StatisticsOpImage</A><BR>
<TD><A name=51856>An abstract base class for image operators that
compute statistics on a given region of an image, and with a given
sampling rate.</A><BR>
<TR vAlign=top>
<TD><A name=56039>UntiledOpImage</A><BR>
<TD><A name=56043>A general class for single-source operations in which
the values of all pixels in the source image contribute to the value of
each pixel in the destination image.</A><BR>
<TR vAlign=top>
<TD><A name=51845>WarpOpImage</A><BR>
<TD><A name=51867>A general implementation of image warping, and a
superclass for other geometric image operations.</A><BR></TR></TBODY></TABLE>
<P>All abstract methods defined in <CODE>OpImage</CODE> must be implemented by
any new <CODE>OpImage</CODE> subclass. Specifically, there are two fundamental
methods that must be implemented:
<P>
<TABLE cellPadding=3 border=3>
<CAPTION><FONT size=-1><B></B></FONT></CAPTION>
<TBODY>
<TR vAlign=top>
<TH><A name=51916>Method </A>
<TH><A name=51918>Description </A>
<TR vAlign=top>
<TD><A name=51920>getTile</A><BR>
<TD><A name=51922>Gets a tile for reading. This method is called by the
object that has the new operator name as its source with a rectangle as
its parameter. The operation is responsible for returning a rectangle
filled in with the correct values.</A><BR>
<TR vAlign=top>
<TD><A name=51924>computeRect</A><BR>
<TD><A name=51926>Computes a rectangle of output, given Raster sources.
The method is called by getTile to do the actual computation. The
extension must override this method.</A><BR></TR></TBODY></TABLE>
<P>First, you have to decide which of the <CODE>OpImage</CODE> subclasses to
extend. To write a new statistics operation, you would most likely extend the
<CODE>StatisticsOpImage</CODE> class. Each subclass has a specific purpose, as
described in <A
href="http://java.sun.com/products/java-media/jai/forDevelopers/jai1_0_1guide-unc/Extension.doc.html#51670">Table
14-1</A>.
<P><A name=51155>
<H3>14.3.2 <IMG src="Extending the API.files/space.gif">Extending the
OperationDescriptor Interface</H3></A>Operations that are to be created using
one of the <CODE>JAI.create</CODE> methods must be defined in the
<CODE>registryFile</CODE>, which is included in the <CODE>jai_core.jar</CODE>.
Each operation has an OperationDescriptor (denoted as "<CODE>odesc</CODE>" in
the <CODE>registryFile</CODE>), which provides a textual description of the
operation and specifies the number and type of its sources and parameters. The
OperationDescriptor also specifies whether the operation supports rendered
mode, renderable mode, or both.
<P><A
href="http://java.sun.com/products/java-media/jai/forDevelopers/jai1_0_1guide-unc/Extension.doc.html#59124">Listing
14-1</A> shows a sample of the <CODE>registryFile</CODE> contents. Note that
this is not the entire <CODE>registryFile</CODE>, only a small sample showing
two operators (absolute and addconst).
<P><CAPTION><FONT size=-1><B><A name=59124>
<CENTER><FONT size=-1><B><I>Listing 14-1 </I><IMG
src="Extending the API.files/sm-blank.gif" border=0> registryFile
Example</B></FONT></CENTER></A>
<P></B></FONT></CAPTION>
<HR>
<TR valign="top"><TD><PRE> odesc javax.media.jai.operator.AbsoluteDescriptor absolute
odesc javax.media.jai.operator.AddConstDescriptor addconst
</PRE><TR valign="top"><TD><PRE> rif com.sun.media.jai.opimage.AbsoluteCRIF
com.sun.media.jai absolute sunabsoluterif
rif com.sun.media.jai.mlib.MlibAbsoluteRIF
com.sun.media.jai absolute mlibabsoluterif
rif com.sun.media.jai.opimage.AddConstCRIF
com.sun.media.jai addconst sunaddconstrif
rif com.sun.media.jai.mlib.MlibAddConstRIF
com.sun.media.jai addconst mlibaddconstrif
</PRE><TR valign="top"><TD><PRE> crif com.sun.media.jai.opimage.AbsoluteCRIF absolute
crif com.sun.media.jai.opimage.AddConstCRIF addconst
</PRE>
<HR>
<P>All high-level operation names in JAI (such as <CODE>Rotate</CODE>,
<CODE>Convolve</CODE>, and <CODE>AddConst</CODE>) are mapped to instances of
<CODE>RenderedImageFactory</CODE> (RIF) and/or
<CODE>ContextualRenderedImageFactory</CODE> (CRIF) that are capable of
instantiating <CODE>OpImage</CODE> chains to perform the named operation. The
RIF is for rendered mode operations only; the CRIF is for operations that can
handle renderable mode or both rendered and renderable modes.
<P>To avoid the problems associated with directly editing the
<CODE>registryFile</CODE> and then repackaging it, you can register
OperationDescriptors and RIFs and CRIFs using the OperationRegistry's
<CODE>registerOperationDescription</CODE>, and <CODE>registerRIF</CODE> and
<CODE>registerCRIF</CODE> methods. The only drawback to this method of
registration is that the new operator will not be automatically reloaded every
time a JAI program is executed., since the operation is not actually present
in the <CODE>registryFile</CODE>. This means that to use the new operation,
the operation will always have to be invoked beforehand.<CODE></CODE>
<P>To temporarily register a new operation:
<P>
<UL>1. <STRONG>Register the operation name</STRONG>.
<P>
<DL><A name=51505>
<DT>
<DD>The high-level operation name, called an <EM>operation
descriptor</EM>, is registered by calling the
<CODE>registerOperationByName()</CODE> method or the
<CODE>registerOperationDescriptor()</CODE> method. The operation
descriptor name must be unique. </A>
<P><A name=59090></P>
<DT>
<DD>Once an operation descriptor is registered, it may be obtained by name
by calling the <CODE>getOperationDescriptor()</CODE> method. </A>
<P></P></DD></DL>2. <STRONG>Register the set of rendered image factory
objects.</STRONG>
<P>
<DL><A name=59101>
<DT>
<DD>The rendered image factory (RIF) is registered using the
<CODE>registerRIF</CODE> method. Each RIF is registered with a specific
operation name and is given a product name. Similar methods exist for
registering a contextual image factory (CRIF). </A>
<P></P></DD></DL></UL>The <CODE>OperationDescriptor</CODE> interface provides
a comprehensive description of a specific image operation. All of the
information regarding the operation, such as the operation name, version,
input, and property, should be listed. Any conditions placed on the operation,
such as its input format and legal parameter range, should also be included,
and the methods to enforce these conditions should be implemented. A set of
<CODE>PropertyGenerator</CODE>s may be specified to be used as a basis for the
⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -