001 /* 002 * ByteChannelImage 003 * 004 * Copyright (c) 2000, 2001, 2002, 2003 Marco Schmidt. 005 * All rights reserved. 006 */ 007 008 package net.sourceforge.jiu.data; 009 010 /** 011 * An extension of the {@link IntegerImage} interface that restricts the image to 012 * byte samples. 013 * The minimum sample value for all channels is <code>0</code>, 014 * the maximum sample value <code>255</code>. 015 * <p> 016 * Number of channels and resolution must be given to the constructor 017 * and cannot be changed after creation. 018 * <p> 019 * Each channel of the image is made up of <code>byte</code> values. 020 * Note that bytes in Java are signed, they can take values from <code>-128</code> to <code>127</code>. 021 * If you use {@link IntegerImage}'s getSample and putSample methods 022 * you don't have to deal with this, you always get <code>int</code> samples 023 * that are in the 0 .. 255 interval. 024 * <p> 025 * To manually convert a Java <code>byte</code> value to an <code>int</code> value 026 * in the range of 0 to 255, do the following: 027 * <pre> 028 * byte b = ...; // initialize byte value 029 * int i = b & 0xff; 030 * // i now is a value between 0 and 255 031 * </pre> 032 * @author Marco Schmidt 033 */ 034 public interface ByteChannelImage extends IntegerImage 035 { 036 /** 037 * Sets all samples of the first channel to the argument byte value. 038 * Equal to <code>clear(0, newValue);</code>. 039 * @param newValue all samples in the first channel are set to this value 040 * @see #clear(int, byte) 041 * @see #clear(int) 042 * @see #clear(int, int) 043 */ 044 void clear(byte newValue); 045 046 /** 047 * Sets all samples of one channel to a new value. 048 * @param channelIndex zero-based index of the channel to be cleared (must be smaller than {@link #getNumChannels()} 049 * @param newValue all samples in the channel will be set to this value 050 */ 051 void clear(int channelIndex, byte newValue); 052 053 /** 054 * Returns a single byte sample from the first channel and the specified position. 055 * A call to this method is the same as <code>getByteSample(0, x, y)</code>. 056 * @param x horizontal position of the sample to be returned (must be between <code>0</code> and {@link #getWidth()}<code> - 1</code> 057 * @param y vertical position of the sample to be returned (must be between <code>0</code> and {@link #getHeight()}<code> - 1</code> 058 * @return the requested byte sample 059 */ 060 byte getByteSample(int x, int y); 061 062 /** 063 * Returns a single byte sample from the image. 064 * When possible, try copying several samples at a time for 065 * higher speed ({@link #getByteSamples}). 066 * @param channel the number of the channel of the sample; must be from <code>0</code> to <code>{@link #getNumChannels()} - 1</code> 067 * @param x the column of the sample to be returned; must be from <code>0</code> to <code>{@link #getWidth()} - 1</code> 068 * @param y the row of the sample; must be from <code>0</code> to <code>{@link #getHeight()} - 1</code> 069 * @return the sample, a single byte value 070 * @throws IllegalArgumentException if the arguments hurt one of the preconditions above 071 * @see #getByteSamples 072 */ 073 byte getByteSample(int channel, int x, int y); 074 075 /** 076 * Copies samples from this image to a byte array. 077 * Copies <code>num</code> samples in row <code>y</code> of channel 078 * <code>channel</code>, starting at horizontal offset <code>x</code>. 079 * Data will be written to the <code>dest</code> array, starting at 080 * offset <code>destOffset</code>. 081 * Data will be copied from one row only, so a maximum of 082 * <code>getWidth()</code> 083 * samples can be copied with a call to this method. 084 * 085 * @param channelIndex the index of the channel to be copied from; must be 086 * from <code>0</code> to <code>getNumChannels() - 1</code> 087 * @param x the horizontal offset where copying will start; must be from 088 * <code>0</code> to <code>getWidth() - 1</code> 089 * @param y the row from which will be copied; must be from 090 * <code>0</code> to <code>getHeight() - 1</code> 091 * @param w the number of columns to be copied 092 * @param h the number of rows to be copied 093 * @param dest the array where the data will be copied to; must have a 094 * length of at least <code>destOffset + num</code> 095 * @param destOffset the offset into <code>dest</code> where this method 096 * will start copying data 097 * @throws IllegalArgumentException if the arguments hurt one of the many 098 * preconditions above 099 */ 100 void getByteSamples(int channelIndex, int x, int y, int w, int h, byte[] dest, int destOffset); 101 102 /** 103 * Sets one byte sample in one channel to a new value. 104 */ 105 void putByteSample(int channel, int x, int y, byte newValue); 106 107 /** 108 * Sets one byte sample in the first channel (index <code>0</code>) to a new value. 109 * Result is equal to <code>putByteSample(0, x, y, newValue);</code>. 110 */ 111 void putByteSample(int x, int y, byte newValue); 112 113 /** 114 * Copies a number of samples from the argument array to this image. 115 */ 116 void putByteSamples(int channel, int x, int y, int w, int h, byte[] src, int srcOffset); 117 }