/usr/share/GNUstep/Documentation/Developer/Gui/ProgrammingManual/AppKit/images.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- (C) 2005-2006 Christopher Armstrong.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2, as published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License".

This documentation is provided on an "AS IS" BASIS, WITHOUT WARRANTY
OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED
TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND USEFULNESS
OF THE DOCUMENTATION IS WITH YOU (THE LICENSEE). IN NO EVENT WILL THE COPYRIGHT
HOLDERS BE LIABLE FOR DAMAGES, INCLUDING ANY DIRECT, INDIRECT,
SPECIAL, GENERAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF
THE USE OR INABILITY TO USE THIS DOCUMENTATION (INCLUDING BUT NOT
LIMITED TO LOSS OF DATA, USE, OR PROFITS; PROCUREMENT OF SUBSTITUTE
GOODS AND SERVICES; OR BUSINESS INTERUPTION) HOWEVER CAUSED, EVEN
IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. -->
<!-- Created by GNU Texinfo 5.2, http://www.gnu.org/software/texinfo/ -->
<head>
<title>Using the GNUstep AppKit 0.1: images</title>

<meta name="description" content="Using the GNUstep AppKit 0.1: images">
<meta name="keywords" content="Using the GNUstep AppKit 0.1: images">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<link href="index.html#Top" rel="start" title="Top">
<link href="conceptindex.html#conceptindex" rel="index" title="conceptindex">
<link href="index.html#Top" rel="up" title="Top">
<link href="fdl.html#fdl" rel="next" title="fdl">
<link href="dataexchange.html#dataexchange" rel="prev" title="dataexchange">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
blockquote.smallquotation {font-size: smaller}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
div.indentedblock {margin-left: 3.2em}
div.lisp {margin-left: 3.2em}
div.smalldisplay {margin-left: 3.2em}
div.smallexample {margin-left: 3.2em}
div.smallindentedblock {margin-left: 3.2em; font-size: smaller}
div.smalllisp {margin-left: 3.2em}
kbd {font-style:oblique}
pre.display {font-family: inherit}
pre.format {font-family: inherit}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: inherit; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: inherit; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.nocodebreak {white-space:nowrap}
span.nolinebreak {white-space:nowrap}
span.roman {font-family:serif; font-weight:normal}
span.sansserif {font-family:sans-serif; font-weight:normal}
ul.no-bullet {list-style: none}
-->
</style>


</head>

<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
<a name="images"></a>
<div class="header">
<p>
Next: <a href="fdl.html#fdl" accesskey="n" rel="next">fdl</a>, Previous: <a href="dataexchange.html#dataexchange" accesskey="p" rel="prev">dataexchange</a>, Up: <a href="index.html#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="conceptindex.html#conceptindex" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<a name="Images-and-Imageviews-1"></a>
<h2 class="chapter">14 Images and Imageviews</h2>

<a name="Images-and-Imageviews"></a><p>GNUstep provides mechanisms for the retreival and display of images. A number of objects beginning with <code>NSImage</code><a name="DOCF17" href="#FOOT17"><sup>17</sup></a> exist, each with slightly different functions.
</p>
<p>An <em>image</em> is represented using an instance of the <code>NSImage</code> class. You can create these using the path or URL of a file, raw image data or a pasteboard.
</p>
<p>Images may contain zero or more image representations, or <em>imagereps</em>. For example, a photographic image may contain both black and white and colour representations, or representations at different resolutions. The purpose of this is to allow GNUstep to select the best representation for a particular device. GNUstep may select a lower-resolution representation for a screen, while selecting the highest resolution representation for printed output. If there was also a vector representation, it may choose to use it for printed output. An imagerep is represented by an instance of a <code>NSImageRep</code> subclass.
</p>
<p>An image by itself is not enough for rendering. Images are rendered on a window using an <code>NSImageView</code> object. These let you set the alignment and scaling for displaying the image. They also let you set a graphical border using the <code>-setFrameStyle:</code> method. <code>NSImageView</code> is a control, so the normal control/cell model applies to it.
</p>
<p>If you only need to display an image on it&rsquo;s own, use <code>NSImageView</code>. For more complicated image rendering, e.g. inside of custom views, use <code>NSImage</code> to draw or composite at a certain point.
</p>
<a name="Using-NSImage"></a>
<h3 class="section">14.1 Using NSImage</h3>

<p>Whether using <code>NSImageView</code> or not, you will have to create an <code>NSImage</code> object. It provides a number of constructors for loading an image with a path, a URL or a data object (<code>NSData</code>). Note that for loading from a file or URL, two sets of methods are provided. These have subtly different meanings, as shown below:
</p>
<dl compact="compact">
<dt><code>-initWithContentsOfFile:</code></dt>
<dt><code>-initWithContentsOfURL:</code></dt>
<dd><p>These methods load the image from the specified location, and create image representations for rendering later.
</p>
</dd>
<dt><code>-initByReferencingFile:</code></dt>
<dt><code>-initByReferencingURL:</code></dt>
<dd><p>These methods don&rsquo;t actually load the image straight away. Instead, when you try to composite or draw the image at a location, it loads the image from disk and generates a representation at that time.
</p>
</dd>
</dl>

<p>From here, an image can be drawn within a view using any of the drawing/compositing/dissolving methods. You can also get at the imagereps using the <code>-representations</code> method (amongst others).
</p>
<a name="Drawing-Images"></a>
<h3 class="section">14.2 Drawing Images</h3>

<p><code>NSImage</code> provides a number of methods for drawing an image. It also provides quite a number means to control how an image is composited at its destination.<a name="DOCF18" href="#FOOT18"><sup>18</sup></a> <em>Compositing</em> refers to the way the image is rendered onto the destination surface.
</p>
<p>Simply drawing an image into your view may be achieved with the <code>-drawRepresentation:inRect:</code> method. In other cases, you may wish to draw it onto a destination surface with a compositing operation, in which case you can use the <code>-drawAtPoint:fromRect:operation:fraction:</code> or <code>-drawInRect:fromRect:operation:fraction:</code> methods.
</p>
<p>These take a rectangle from the source image, and composite it onto a destination surface. The compositing operation specifies how the image is blended with the destination surface, and is a constant in <code>NSCompositingOperation</code>. These constants define what the destination image looks like after a composite, as a result of combining the source and destination image. <a name="DOCF19" href="#FOOT19"><sup>19</sup></a>
</p><dl compact="compact">
<dt><code>NSCompositeClear</code></dt>
<dd><p>The destination is left transparent.
</p>
</dd>
<dt><code>NSCompositeCopy</code></dt>
<dd><p>The source image appears at the destination.
</p>
</dd>
<dt><code>NSCompositeSourceOver</code></dt>
<dd><p>The source image appears wherever it is opaque, and the destination image elsewhere.
</p>
</dd>
<dt><code>NSCompositeSourceIn</code></dt>
<dd><p>The source image appears wherever both the source and destination are opaque, and is transparent elsewhere.
</p>
</dd>
<dt><code>NSCompositeSourceOut</code></dt>
<dd><p>The source image appears where the source image is opaque but the destination image is transparent, and is transparent elsewhere.
</p>
</dd>
<dt><code>NSCompositeSourceAtop</code></dt>
<dd><p>The source image appears wherever both images are opaque, the destination appears wherever the destination is opaque but the source image is transparent, and the result is transparent elsewhere.
</p>
</dd>
<dt><code>NSCompositeDestinationOver</code></dt>
<dd><p>The destination image appears wherever it is opaque, and the source image elsewhere.
</p>
</dd>
<dt><code>NSCompositeDestinationIn</code></dt>
<dd><p>The destination image appears where both images are opaque, and the result is transparent elsewhere.
</p>
</dd>
<dt><code>NSCompositeDestinationOut</code></dt>
<dd><p>The destination image appears wherever it is opaque but the source image is transparent, and it is transparent elsewhere.
</p>
</dd>
<dt><code>NSCompositeDestinationAtop</code></dt>
<dd><p>The destination image appears wherever both images are opaque, the source image appears wherever the source image is opaque but the destination is transparent, and the result is transparent elsewhere.
</p>
</dd>
<dt><code>NSCompositeXOR</code></dt>
<dd><p>The result of and exclusive OR operation between the bits defining the pixels in bothe images.
</p>
</dd>
<dt><code>NSCompositePlusDarker</code></dt>
<dd><p>The result of adding the values of the colour components of the pixels in both images, with the result approaching zero as a limit.
</p>
</dd>
<dt><code>NSCompositePlusLighter</code></dt>
<dd><p>The result of adding the values of the colour components of the pixels in both images, with the result approaching one as a limit.
</p></dd>
</dl>

<p>The <var>fraction</var> parameter corresponds to the coverage of the source alpha channel with zero making the source transparent and one making the source fully opaque.
</p>
<a name="Working-with-image-representations"></a>
<h3 class="section">14.3 Working with image representations</h3>

<p>Quite a number of classes inherit from <code>NSImageRep</code> to provide means to load different types of image formats, such as bitmaps, TIFF images, etc:
</p><dl compact="compact">
<dt><code>NSBitmapImageRep</code></dt>
<dd><p>For bitmap (raster) images, <code>NSBitmapImageRep</code> is used. PNG, JPG and TIFF image file formats would be represented with the class. 
</p>
<p>You can retreive information about the image with methods such as <code>-bitsPerPixel</code> or <code>-isPlanar</code>. For image formats that can store metadata (such as resolution information or camera settings), the <code>-valueForProperty:</code> and <code>-setProperty:withValue:</code> methods can be used to manipulate it.
</p>
<p>If necessary, it contains initialisers for instantiating it from raw data(<code>-initWithData:</code>) and from the display (<code>-initWithFocusedViewRect:</code>.
</p>
</dd>
<dt><code>NSCachedImageRep</code></dt>
<dd><p>This image representation is cached bitmap left over from the result of executing some instructions or data. It lives inside an off-screen window.
</p>
</dd>
<dt><code>NSCustomImageRep</code></dt>
<dd><p>These are representations which can be drawn in a manner that is defined by the application. You initialize these with a selector that is executed against a delegate object when <code>-draw</code> is called on the representation.
</p>
</dd>
<dt><code>NSEPSImageRep</code></dt>
<dd><p>Unsupported.
</p>
</dd>
</dl>

<p>The <code>NSImageRep</code> class itself also provides a number of methods for gaining information about what kinds of file formats GNUstep supports, and for instantiating images dynamically based on raw image data or the contents of a file or URL.
</p>



<div class="footnote">
<hr>
<h4 class="footnotes-heading">Footnotes</h4>

<h3><a name="FOOT17" href="#DOCF17">(17)</a></h3>
<p>Including NSImage</p>
<h3><a name="FOOT18" href="#DOCF18">(18)</a></h3>
<p>Note that many of the mechanisms provided for compositing may not be supported in some backends i.e. the Windows backend.</p>
<h3><a name="FOOT19" href="#DOCF19">(19)</a></h3>
<p>These compositing operations are the same as those described in the (now well-studied) academic paper, <cite>Compositing Digital Images</cite> by Thomas Porter and Tom Duff in 1984.</p>
</div>
<hr>
<div class="header">
<p>
Next: <a href="fdl.html#fdl" accesskey="n" rel="next">fdl</a>, Previous: <a href="dataexchange.html#dataexchange" accesskey="p" rel="prev">dataexchange</a>, Up: <a href="index.html#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="conceptindex.html#conceptindex" title="Index" rel="index">Index</a>]</p>
</div>



</body>
</html>
gnustep-gui-doc 0.24.0-3 / usr / share / GNUstep / Documentation / Developer / Gui / ProgrammingManual / AppKit / images.html
