Static Public Attributes

FCam::Image Class Reference

A reference-counted Image object. More...

#include <Image.h>

Collaboration diagram for FCam::Image:
Collaboration graph
[legend]

List of all members.

Public Member Functions

Image property accessors

These methods return values of the various Image properties, which are immutable for a given Image instance.

Size size () const
 The size of the image in pixels.
unsigned int width () const
 The width of the image in pixels.
unsigned int height () const
 The height of the image in pixels.
ImageFormat type () const
 The format of the image data.
unsigned int bytesPerPixel () const
 The size of an image pixel in bytes.
unsigned int bytesPerRow () const
 The increment between two rows of the image in bytes.
bool valid () const
 Test if it's safe to access the image data.
bool discard () const
 Test if this image is a special Discard image.
bool autoAllocate () const
 Test if this image is a special AutoAllocate image.
Allocating Constructors and Factory Methods

These image constructors allocate new memory for image data.

 Image (Size, ImageFormat)
 Construct a new image of the given size in the given format.
 Image (int, int, ImageFormat)
 Construct a new image of the given size in the given format.
Image copy () const
 Returns an Image containing a copy of the current Image's data.
Non-allocating Constructors and Factory Methods

These image constructors make a new reference to already existing image data.

 Image (Size, ImageFormat, unsigned char *, int srcBytesPerRow=-1)
 Construct a new image of the given size in the given format using already existing data.
 Image (int, int, ImageFormat, unsigned char *, int srcBytesPerRow=-1)
 Construct a new image of the given size in the given format using already existing data.
 Image ()
 Construct a new image with no memory allocated.
 Image (const Image &other)
 Make a copy of the image reference.
Image subImage (unsigned int x, unsigned int y, Size) const
 Retuns an image that points to a section of the current image.
const Imageoperator= (const Image &other)
 Become a new reference to an existing image.
Image data accessors

These methods allow you to change the pixel data referenced by the Image.

unsigned char * operator() (unsigned int x, unsigned int y) const
 Access a pixel in the image.
void copyFrom (const Image &)
 Copies the image data from the source Image into this Image.
Miscellaneous methods

bool lock (int timeout=-1)
 Lock the image to prevent other threads writing to it with a configurable timeout in microseconds.
void unlock ()
 Unlock the image.
bool operator== (const Image &) const
 Compare two images for equality.
void debug (const char *name="") const
 Print out some debugging info about the image, optionally taking in a name to identify the image.

Static Public Attributes

static unsigned char * Discard = (unsigned char *)(0)
 This value for data represents an image with no allocated memory that should never have data copied into it.
static unsigned char * AutoAllocate = (unsigned char *)(-1)
 This value for data represents image data whose first user should allocate memory for.

Detailed Description

A reference-counted Image object.

Images are stored in row-major order, with the origin is the top left corner of the image. While each scanline is guaranteed to be consecutive in memory, there may be padding in between adjacent scanlines.

If you instantiate an image using one of the constructors that allocates data, the result will be a reference counted image object, that automatically deletes the data when the last reference to it is destroyed.

If you use a constructor that sets the data field, you're telling the image class that someone else is managing that memory, and the destructor will never be called.

Either way, you can safely pass Image objects by value without incurring the cost of memory copies. Only the explicit copy methods will copy the underlying image data.

Definition at line 34 of file Image.h.


Constructor & Destructor Documentation

FCam::Image::Image ( Size  s,
ImageFormat  f 
)

Construct a new image of the given size in the given format.

Definition at line 37 of file Image.cpp.

FCam::Image::Image ( int  w,
int  h,
ImageFormat  f 
)

Construct a new image of the given size in the given format.

Definition at line 21 of file Image.cpp.

FCam::Image::Image ( Size  s,
ImageFormat  f,
unsigned char *  d,
int  srcBytesPerRow = -1 
)

Construct a new image of the given size in the given format using already existing data.

The image will never deallocate this data. This is a good way to cast some other image type to FCam's image type without allocating new data or copying image data. These constructors optionally take in the number of bytes per row of image data, to allow for Images that contain a subset of the source data, or for source data with padding.

Definition at line 53 of file Image.cpp.

FCam::Image::Image ( int  w,
int  h,
ImageFormat  f,
unsigned char *  d,
int  srcBytesPerRow = -1 
)

Construct a new image of the given size in the given format using already existing data.

The image will never deallocate this data. This is a good way to cast some other image type to FCam's image type without allocating new data or copying image data. These constructors optionally take in the number of bytes per row of image data, to allow for Images that contain a subset of the source data, or for source data with padding.

Definition at line 72 of file Image.cpp.

FCam::Image::Image ( const Image other  ) 

Make a copy of the image reference.

Doesn't copy image data, just produces a new reference to the same data.

Definition at line 95 of file Image.cpp.


Member Function Documentation

Size FCam::Image::size (  )  const [inline]

The size of the image in pixels.

Note: The image size in memory is not necessarily equal to size.width*size.height*bytesPerPixel, since bytesPerRow may be larger than size.width*bytesPerPixel if dealing with aligned images or subimages. The true image memory extent is size.height*bytesPerRow.

Definition at line 51 of file Image.h.

unsigned int FCam::Image::width (  )  const [inline]

The width of the image in pixels.

Definition at line 56 of file Image.h.

unsigned int FCam::Image::height (  )  const [inline]

The height of the image in pixels.

Definition at line 61 of file Image.h.

unsigned int FCam::Image::bytesPerPixel (  )  const [inline]

The size of an image pixel in bytes.

This is strictly equal to FCam::bytesPerPixel(type()), and is cached here for convenience

Definition at line 76 of file Image.h.

unsigned int FCam::Image::bytesPerRow (  )  const [inline]

The increment between two rows of the image in bytes.

This is the number of bytes you have to increment by to move from one row to the next. That is, pixel (x,y) is located at memory location data+y*bytesPerRow+x*bytesPerPixel. bytesPerRow is at least equal to size.width*bytesPerPixel, but may be larger for a subimage (an image that's only a region of a larger source image), or an image that has rows aligned in memory for faster access.

Definition at line 91 of file Image.h.

bool FCam::Image::discard (  )  const [inline]

Test if this image is a special Discard image.

When passed as an argument to a function, a Discard image indicates that the function should not produce any image output, but should perform all its other tasks. Passing a Shot object with a Discard image to a Sensor results in a Frame with a non-valid Image, but all device actions are performed, and all Frame metadata, such as histogram data or Device tags, are valid. You can create a Discard image with: Image(size, type, Image::Discard)

Definition at line 111 of file Image.h.

bool FCam::Image::autoAllocate (  )  const [inline]

Test if this image is a special AutoAllocate image.

When passed as an argument to a function, an AutoAllocate image indicates that the function should create a new Image to store the results in, based on the attributes of the Image passed in. Passing a Shot object with an AutoAllocate image to a Sensor makes the Sensor allocate a new buffer for the captured image data, which is returned in the Frame. This allows you to reuse the same Shot object for multiple capture requests (or a stream request) without getFrame() overwriting the data for an earlier Frame image. You can create an AutoAllocate image with: Image(size, type, Image::AutoAllocate)

Definition at line 128 of file Image.h.

Image FCam::Image::copy (  )  const

Returns an Image containing a copy of the current Image's data.

Useful for converting an Image with a weak reference to an Image with a strong reference to its data. This requires a full copy of the underlying image data, so it can be quite slow for large images.

Definition at line 159 of file Image.cpp.

Image FCam::Image::subImage ( unsigned int  x,
unsigned int  y,
Size  s 
) const

Retuns an image that points to a section of the current image.

The subimage shares the same underlying buffer. The requested size will be trimmed if it would exceed the bounds of the current image. The arguments are the location of the top-left corner of the subImage and the size of the subImage.

Definition at line 131 of file Image.cpp.

const Image & FCam::Image::operator= ( const Image other  ) 

Become a new reference to an existing image.

This never copies image data. It just produces a new reference to the same data, with the same properties.

Definition at line 108 of file Image.cpp.

unsigned char* FCam::Image::operator() ( unsigned int  x,
unsigned int  y 
) const [inline]

Access a pixel in the image.

Returns a pointer to the first byte of a pixel at image location (x,y). The image is laid out in memory in row-major order. Each row is contigious, and there may be a gap between rows, with each row y of pixels starting at memory offset y * bytesPerRow() . Each row itself is width() * bytesPerPixel() bytes long.

Definition at line 227 of file Image.h.

void FCam::Image::copyFrom ( const Image srcImage  ) 

Copies the image data from the source Image into this Image.

Useful for transferring image blocks into pre-allocated (possibly weakly-referenced) buffers. Mismatched sizes are allowed. In case of a larger source image, only the section that fits into this image will be copied. In case of a smaller source image, the pixels in this Image outside the source image's area are not modified. Ignores image types entirely. Actually copies image data, so can be quite slow.

Definition at line 173 of file Image.cpp.

bool FCam::Image::lock ( int  timeout = -1  ) 

Lock the image to prevent other threads writing to it with a configurable timeout in microseconds.

Returns whether the lock was acquired.

The default timeout (-1) indicates you should wait indefinitely, and should always return true. A timeout of zero will not block at all.

Images have locks to coordinate access between multiple threads. When new frames come in, the FCam API will try to lock the target image for them with a short timeout and copy the data in. If the image is still locked at the end of the timeout, it will instead drop the data on the floor (avoiding the expensive memcpy). You can use this for rate control of a viewfinder like so:

         Shot viewfinder;
         ...
         viewfinder.image = Image(640, 480, UYUV);
         ...
         sensor.stream(viewfinder);
         while (1) {
             // Get the most recent viewfinder frame with image data
             Frame f;
             do {
                 f = sensor.getFrame();
                 // feed the frame to the autoexposure and autofocus routines
                 ...
             } while (sensor.framesPending() || !f.image().valid());
           
             f.image().lock();
             // Do something expensive with the image. 
             // No memcpys into the image will take place during this time.
             f.image().unlock();
         }        
         

If you absolutely want to save every piece of image data, you should set the target image to an AutoAllocated one, Even the example above doesn't guarantee image data hasn't been clobbered just before you call lock(). It only guarantees you get one consistent image and not a half-written one. If you spend all your CPU time with the frame locked, you may starve the FCam runtime of chances to give you new image data.

Your image may still get clobbered if other threads don't respect the lock, or if the image is a weak reference, and other independently created weak references to the same data exist are being used to write to it. Best to only have one image that refers to external data (images created by other libraries, framebuffers, etc), and construct other references to that data using copies of the first image.

Definition at line 224 of file Image.cpp.

void FCam::Image::unlock (  ) 

Unlock the image.

See lock for details.

Definition at line 251 of file Image.cpp.

bool FCam::Image::operator== ( const Image other  )  const

Compare two images for equality.

Two images are equal if they view the same image data with the same attributes, so two offset subimages of a larger image won't be equal, and neither would two subimages of the same region, if one has a different type than the other.

Definition at line 265 of file Image.cpp.


Member Data Documentation

unsigned char * FCam::Image::Discard = (unsigned char *)(0) [static]

This value for data represents an image with no allocated memory that should never have data copied into it.

It is equal to NULL.

Definition at line 138 of file Image.h.

unsigned char * FCam::Image::AutoAllocate = (unsigned char *)(-1) [static]

This value for data represents image data whose first user should allocate memory for.

If used as the image field of a Shot, it indicates that a new buffer should be allocated for every new frame.

Definition at line 145 of file Image.h.


The documentation for this class was generated from the following files: