From 7c8909d49664262f477c06e1b3b501f5082d1aa5 Mon Sep 17 00:00:00 2001
From: msjid <majidgeravand@gfuse.it>
Date: Fri, 28 Aug 2026 18:46:13 +0200
Subject: [PATCH] Add comprehensive README documentation

Includes project overview, features, build instructions, API reference,
usage examples, and notes on memory management.

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PZax2uzbHdkL7ukmmF9C3C
---
 README.md | 125 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 125 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..80e3cf8
--- /dev/null
+++ b/README.md
@@ -0,0 +1,125 @@
+# CPP Buffer Template
+
+A generic C++ template-based buffer system designed for efficiently managing and storing image and odometry data.
+
+## Overview
+
+This project demonstrates a reusable `Buffer` template class that provides a flexible way to manage collections of data with optional associated metadata (odometry information). It's particularly useful for robotics and computer vision applications where you need to buffer sensor data.
+
+## Features
+
+- **Generic Template Design**: Works with any data type via C++ templates
+- **Flexible Data Storage**: Supports storing single or multiple data items per buffer
+- **Metadata Support**: Optionally associate metadata (e.g., odometry data) with stored items
+- **Configuration Tracking**: Query buffer state and size information
+- **Simple API**: Intuitive `push()` and `read()` interface
+
+## Project Structure
+
+```
+CPP_buffer_template/
+├── CMakeLists.txt          # CMake build configuration
+├── README.md               # This file
+├── include/
+│   └── buffer.hpp          # Buffer template class definition
+└── src/
+    └── main.cpp            # Example usage and demonstration
+```
+
+## Building
+
+### Requirements
+
+- C++11 or later
+- CMake 3.4 or higher
+- A C++ compiler (g++, clang, etc.)
+
+### Build Steps
+
+```bash
+mkdir build
+cd build
+cmake ..
+make
+```
+
+### Running
+
+After building, run the demonstration:
+
+```bash
+./p_demo_04_template_buffer
+```
+
+## Usage
+
+### Basic Example
+
+```cpp
+#include "buffer.hpp"
+
+// Create a buffer for storing image data (pair of pointers) and odometry data
+Buffer<std::pair<u_char*,u_char*>, double> buffer;
+
+// Push a single data item
+u_char* depth = (u_char*)calloc(100, sizeof(u_char));
+u_char* left = (u_char*)calloc(100, sizeof(u_char));
+buffer.push(std::pair<u_char*,u_char*>(depth, left));
+
+// Read the stored data
+std::vector<std::pair<u_char*,u_char*>>* data = buffer.read();
+
+// Access configuration (size and timestamp)
+auto cfg = buffer.config();
+std::cout << "Buffer size: " << cfg.first << std::endl;
+```
+
+### API Reference
+
+#### Constructor
+```cpp
+Buffer<T1, T2>()
+```
+Creates an empty buffer.
+
+#### Push Methods
+```cpp
+void push(T1 input)                              // Store single item
+void push(T1 input_1, T2* input_2)              // Store item with metadata
+void push(T1 input_1, T1 input_2)               // Store two items
+void push(T1 input_1, T1 input_2, T2* input_3) // Store two items with metadata
+```
+
+#### Read Methods
+```cpp
+std::vector<T1>* read()        // Get pointer to stored items
+T2* read_odom()                // Get metadata pointer
+int64_t time()                 // Get timestamp
+std::pair<std::size_t, int64_t> config()  // Get size and timestamp
+```
+
+## Template Parameters
+
+- **T1**: The primary data type to store (e.g., `std::pair<u_char*, u_char*>` for image pairs)
+- **T2**: The metadata type to associate with stored data (e.g., `double` for odometry values)
+
+## Example Use Cases
+
+1. **Robotics**: Buffer sensor frames (RGB, depth) along with odometry data from the robot's pose
+2. **Computer Vision**: Queue image frames from multiple cameras
+3. **Data Processing**: Temporarily store processing results with associated context
+
+## Notes
+
+- The buffer uses dynamic memory management (pointers); ensure proper cleanup to avoid memory leaks
+- The `odom` metadata pointer is optional and defaults to `nullptr`
+- The timestamp field (`t`) is initialized to 0; it can be updated if needed
+- The buffer stores raw pointers - ensure the pointed-to data remains valid during the buffer's lifetime
+
+## License
+
+This project is part of the gfuse-show-cases repository.
+
+## Author
+
+Created as a demonstration of C++ template programming and generic buffer management patterns.