1 // This is core/vil/vil_image_resource.h
2 #ifndef vil_image_resource_h_
3 #define vil_image_resource_h_
4 //:
5 // \file
6 // \brief Representation of a generic image source or destination.
7 //
8 // \author Ian Scott
9 // \date 20 Sep 2002
10 
11 #include "vil_image_view_base.h"
12 #include <cassert>
13 #ifdef _MSC_VER
14 #  include <vcl_msvc_warnings.h>
15 #endif
16 #include <vcl_atomic_count.h>
17 #include "vil_smart_ptr.h"
18 #include "vil_pixel_format.h"
19 
20 #include "vil_image_resource_sptr.h"
21 
22 //:
23 // Abstract representation of an image source or image destination.
24 // Most references to vil_image_resource objects should usually be done
25 // through smart pointers - vil_image_resource_sptr;
26 //
27 // All image data is presumed to be in planes, not components. This
28 // does not say whether the data is stored on disk or in memory
29 // as RGBRGBRGB.. or RRR..GGG..BBB.., just that the interface will
30 // always tell you that it has a multi-plane single-component view.
31 class vil_image_resource
32 {
33  public:
34   vil_image_resource();
35   virtual ~vil_image_resource();
36 
37   //: Dimensions:  Planes x ni x nj.
38   // This concept is treated as a synonym to components.
39   virtual unsigned nplanes() const = 0;
40   //: Dimensions:  Planes x ni x nj.
41   // The number of pixels in each row.
42   virtual unsigned ni() const = 0;
43   //: Dimensions:  Planes x ni x nj.
44   // The number of pixels in each column.
45   virtual unsigned nj() const = 0;
46 
47   //: Pixel Format.
48   //  A standard RGB RGB RGB of chars image has
49   // pixel_format() == VIL_PIXEL_FORMAT_BYTE
50   virtual enum vil_pixel_format pixel_format() const = 0;
51 
52   //: Create a read/write view of the data.
53   // Modifying this view might modify the actual data.
54   // If you want to modify this data in place, call put_view after you done, and
55   // it should work efficiently. This function will always return a
56   // multi-plane scalar-pixel view of the data.
57   // \return 0 if unable to get view of correct size, or if resource is write-only.
58   //
59   // If you want to fill an existing view (e.g. a window onto some other image),
60   // then use
61   // \verbatim
62   // vil_reformat(data->get_view(..), window);
63   //\endverbatim
get_view(unsigned i0,unsigned n_i,unsigned j0,unsigned n_j)64   virtual vil_image_view_base_sptr get_view(unsigned i0, unsigned n_i,
65                                             unsigned j0, unsigned n_j) const
66   { return get_copy_view (i0, n_i, j0, n_j); }
67 
68   //: Create a read/write view of all the data.
get_view()69   vil_image_view_base_sptr get_view() const
70   { return get_view (0, ni(), 0, nj()); }
71 
72   //: Create a read/write view of a copy of this data.
73   // This function will always return a
74   // multi-plane scalar-pixel view of the data.
75   // \return 0 if unable to get view of correct size, or if resource is write-only.
76   virtual vil_image_view_base_sptr get_copy_view(unsigned i0, unsigned n_i,
77                                                  unsigned j0, unsigned n_j) const = 0;
78 
79   //: Create a read/write view of a copy of all the data.
get_copy_view()80   vil_image_view_base_sptr get_copy_view() const
81   { return get_copy_view (0, ni(), 0, nj()); }
82 
83   //: Put the data in this view back into the image source.
84   // The view must be of scalar components. Assign your
85   // view to a scalar-component view if this is not the case.
86   // \return false if failed, because e.g. resource is read-only,
87   // format of view is not correct (if it is a compound pixel type, try
88   // assigning it to a multi-plane scalar pixel view.)
89   virtual bool put_view(const vil_image_view_base& im, unsigned i0, unsigned j0) = 0;
90 
91   //: Put the data in this view back into the image source at the origin
put_view(const vil_image_view_base & im)92   virtual bool put_view(const vil_image_view_base& im)
93   { return put_view(im, 0, 0); }
94 
95   //: Check that a view will fit into the data at the given offset.
96   // This includes checking that the pixel type is scalar.
97   virtual bool view_fits(const vil_image_view_base& im, unsigned i0, unsigned j0);
98 
99   //: Return a string describing the file format.
100   // Only file images have a format, others return 0
file_format()101   virtual char const* file_format() const { return nullptr; }
102 
103   //: Extra property information
104   virtual bool get_property(char const* tag, void* property_value = nullptr) const =0;
105 
106  protected:
107   // You probably should not use a vil_image_resource in a vbl_smart_ptr, so the
108   // ref functions are private
109   friend class vil_smart_ptr<vil_image_resource>;
ref()110   void ref() { ++reference_count_; }
unref()111   void unref() {
112     assert(reference_count_>0);
113     if (--reference_count_<=0) delete this;}
114   vcl_atomic_count reference_count_;
115 };
116 
117 #endif // vil_image_resource_h_
118