diff --git a/src/main/java/net/imglib2/converter/readwrite/SamplerConverter.java b/src/main/java/net/imglib2/converter/readwrite/SamplerConverter.java index fa188ef21..9fbbfea9b 100644 --- a/src/main/java/net/imglib2/converter/readwrite/SamplerConverter.java +++ b/src/main/java/net/imglib2/converter/readwrite/SamplerConverter.java @@ -11,13 +11,13 @@ * %% * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions are met: - * + * * 1. Redistributions of source code must retain the above copyright notice, * this list of conditions and the following disclaimer. * 2. Redistributions in binary form must reproduce the above copyright notice, * this list of conditions and the following disclaimer in the documentation * and/or other materials provided with the distribution. - * + * * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE @@ -35,10 +35,37 @@ package net.imglib2.converter.readwrite; import net.imglib2.Sampler; +import net.imglib2.converter.Converters; +import net.imglib2.type.Type; /** - * TODO - * + * This interface converts a {@link Sampler Sampler<A>} into an instance + * of {@code B}, where {@code A} and {@code B} are typically {@link Type}s. + *

+ * Its intended use is to create objects that wrap the provided + * {@code Sampler} itself instead of wrapping values obtained through the + * {@code Sampler}. In other words, if the {@code Sampler} is pointed at a + * different object, existing objects returned by this + * {@code SamplerConverter} should point at it as well. + *

+ * {@code SamplerConverter}s are used in {@link Converters} to create on-the-fly + * converted images that are both readable and writable. For example, consider + * accessing a channel of an {@code ARGBType} image as {@code UnsignedByteType}. + * The converted image needs to provide converted samplers (e.g., {@code + * RandomAccess}) that "translate" to the samplers of the + * original image (e.g., {@code RandomAccess}). + *

+ * The converted {@code Sampler} returns an {@code UnsignedByteType} instance on + * {@code get()}. If {@code .setByte(10)} is called on that {@code + * UnsignedByteType} instance, that must be translated back to the underlying + * {@code ARGBType}. To achieve this, {@code SamplerConverter.convert(...)} + * creates a special {@code UnsignedByteType} instance which knows about a + * specific source sampler (e.g., {@code RandomAccess}). When the + * {@code UnsignedByteType} instance is written to (or read from), it gets the + * current {@code ARGBType} from the source sampler and performs the conversion. + * + * @param The type of values accessed by the {@link Sampler}. + * @param The type of the value returned by this {@link SamplerConverter}. */ public interface SamplerConverter< A, B > {