# Core ## Frame A `frame` is one of the many images in an acquisition sequence. They are ordered by index. Frames are generated by the acquisition part of the hardware plugin, injected in the processing graph and recycled when the frame is not used (e.g. saved to file). A `frame` is a lightweight object that represents a range of pixels. It can be associated to a memory resource that is reference counted with the frame so that memory is released when it's not referenced by any frame object. The definition of Resource is broad enough to accommodate with the different usages, either owning the memory buffer for the pixels (Container) or mapping a memory zone allocated by a third party (View). ```cpp template class frame { public: typedef ... const_view_t; typedef ... view_t; typedef std::ptrdiff_t x_coord_t; typedef std::ptrdiff_t y_coord_t; typedef point point_t; frame() = default; frame(frame const& other) = default; template frame(View const& view) template frame(View const& view, Resource resource) template frame(frame const& other) frame& operator=(frame const& rhs); template frame& operator=(frame const& rhs) std::size_t num_channels() const; point_t dimensions() const; size_type size() const; x_coord_t width() const; y_coord_t height() const; }; ``` For consistency with Boost.GIL image concept, the view can be retrieved with ```cpp const const_view_t& const_view(const Frame&); const view_t& view(Frame&); ``` Tracking the ownership of the resource associated with the frame is handled with a `shared_ptr`. Internally type erasure is used so that the frame type is not parametrized with the resource. Let's consider a couple of examples: ```cpp // GIL.Image as a resource // construct a shared image auto img = std::make_shared(dimensions); // pass the shared image as frame resource frame_t frm(gil::view(*img), img); ``` ```cpp // RAW data as a resource // construct an array of pixel gil::gray8_pixel_t pixels[32 * 32]; // construct a view from the buffer and use the Deleter of the shared_ptr to manage memory frame_t frm( gil::interleaved_view(32, 32, pixels, 32), std::shared_ptr(pixels, [](auto ptr) { /* do something with the ptr */ })); ``` ```cpp // RAW data as a resource // construct an array of pixel gil::gray8_pixel_t pixels[32 * 32]; // construct a view from the buffer and use the Deleter of the shared_ptr to manage memory frame_t frm( gil::interleaved_view(32, 32, pixels, 32), std::shared_ptr(pixels, [](auto ptr) { /* do something with the ptr */ })); ``` ## Metadata Metadata are attached to a frame and can be augmented by the processing pipeline. ### Typed Metadata `frame.metadata` ### Attributes Attributes are basically annotations or text metadata. `frame.attributes`