2016-11-16 04:31:32 +00:00
|
|
|
//
|
2016-11-16 14:57:17 +00:00
|
|
|
// TextureBuilder.hpp
|
2016-11-16 04:31:32 +00:00
|
|
|
// Clock Signal
|
|
|
|
//
|
|
|
|
// Created by Thomas Harte on 08/03/2016.
|
|
|
|
// Copyright © 2016 Thomas Harte. All rights reserved.
|
|
|
|
//
|
|
|
|
|
2016-11-16 14:57:17 +00:00
|
|
|
#ifndef Outputs_CRT_Internals_TextureBuilder_hpp
|
|
|
|
#define Outputs_CRT_Internals_TextureBuilder_hpp
|
2016-11-16 04:31:32 +00:00
|
|
|
|
|
|
|
#include <cstdint>
|
2016-12-06 12:24:07 +00:00
|
|
|
#include <functional>
|
2016-11-16 04:31:32 +00:00
|
|
|
#include <memory>
|
|
|
|
#include <vector>
|
|
|
|
|
|
|
|
#include "OpenGL.hpp"
|
|
|
|
#include "CRTConstants.hpp"
|
|
|
|
|
|
|
|
namespace Outputs {
|
|
|
|
namespace CRT {
|
|
|
|
|
|
|
|
/*!
|
2016-11-16 15:14:15 +00:00
|
|
|
Owns an OpenGL texture resource and provides mechanisms to fill it from bottom left to top right
|
2016-11-16 04:31:32 +00:00
|
|
|
with runs of data, ensuring each run is neighboured immediately to the left and right by copies of its
|
|
|
|
first and last pixels.
|
2017-07-08 02:25:05 +00:00
|
|
|
|
|
|
|
Intended usage:
|
|
|
|
|
|
|
|
(i) allocate a write area with allocate_write_area, supplying a maximum size.
|
|
|
|
(ii) call reduce_previous_allocation_to to announce the actual size written.
|
|
|
|
|
|
|
|
This will cause you to have added source data to the target texture. You can then either use that data
|
|
|
|
or allow it to expire.
|
|
|
|
|
|
|
|
(iii) call retain_latest to add the most recently written write area to the flush queue.
|
|
|
|
|
|
|
|
The flush queue contains provisional data, that can sit in the CPU's memory space indefinitely. This facility
|
|
|
|
is provided because it is expected that a texture will be built alontside some other collection of data —
|
|
|
|
that data in the flush queue is expected to become useful in coordination with something else but should
|
|
|
|
be retained at least until then.
|
|
|
|
|
|
|
|
(iv) call flush to move data to the submit queue.
|
|
|
|
|
|
|
|
When you flush, you'll receive a record of the bounds of all newly-flushed areas of source data. That gives
|
|
|
|
an opportunity to correlate the data with whatever else it is being tied to. It will continue to sit in
|
|
|
|
the CPU's memory space but has now passed beyond any further modification or reporting.
|
|
|
|
|
|
|
|
(v) call submit to move data to the GPU and free up its CPU-side resources.
|
|
|
|
|
|
|
|
The data is now on the GPU, for whatever use the caller desires.
|
|
|
|
|
2016-11-16 04:31:32 +00:00
|
|
|
*/
|
2016-11-16 14:57:17 +00:00
|
|
|
class TextureBuilder {
|
2016-11-16 04:31:32 +00:00
|
|
|
public:
|
2016-11-16 15:13:06 +00:00
|
|
|
/// Constructs an instance of InputTextureBuilder that contains a texture of colour depth @c bytes_per_pixel;
|
|
|
|
/// this creates a new texture and binds it to the current active texture unit.
|
2016-11-17 04:26:04 +00:00
|
|
|
TextureBuilder(size_t bytes_per_pixel, GLenum texture_unit);
|
2016-11-16 15:13:06 +00:00
|
|
|
virtual ~TextureBuilder();
|
2016-11-16 04:31:32 +00:00
|
|
|
|
|
|
|
/// Finds the first available space of at least @c required_length pixels in size. Calls must be paired off
|
|
|
|
/// with calls to @c reduce_previous_allocation_to.
|
2016-11-16 05:15:50 +00:00
|
|
|
/// @returns a pointer to the allocated space if any was available; @c nullptr otherwise.
|
|
|
|
uint8_t *allocate_write_area(size_t required_length);
|
2016-11-16 04:31:32 +00:00
|
|
|
|
|
|
|
/// Announces that the owner is finished with the region created by the most recent @c allocate_write_area
|
|
|
|
/// and indicates that its actual final size was @c actual_length.
|
|
|
|
void reduce_previous_allocation_to(size_t actual_length);
|
|
|
|
|
2017-07-08 02:25:05 +00:00
|
|
|
/// Allocated runs are provisional; they will not appear in the next flush queue unless retained.
|
2017-07-09 21:50:22 +00:00
|
|
|
/// @returns @c true if a retain succeeded; @c false otherwise.
|
|
|
|
bool retain_latest();
|
2017-07-08 02:25:05 +00:00
|
|
|
|
2016-11-16 05:15:50 +00:00
|
|
|
/// @returns @c true if all future calls to @c allocate_write_area will fail on account of the input texture
|
|
|
|
/// being full; @c false if calls may succeed.
|
2016-11-16 04:31:32 +00:00
|
|
|
bool is_full();
|
|
|
|
|
2016-11-16 15:13:06 +00:00
|
|
|
/// Updates the currently-bound texture with all new data provided since the last @c submit.
|
|
|
|
void submit();
|
|
|
|
|
2016-12-04 01:47:19 +00:00
|
|
|
struct WriteArea {
|
2016-12-06 12:24:07 +00:00
|
|
|
uint16_t x, y, length;
|
2016-12-04 01:47:19 +00:00
|
|
|
};
|
2016-12-07 00:08:55 +00:00
|
|
|
/// Finalises all write areas allocated since the last call to @c flush. Only finalised areas will be
|
|
|
|
/// submitted upon the next @c submit. The supplied function will be called with a list of write areas
|
|
|
|
/// allocated, indicating their final resting locations and their lengths.
|
2016-12-06 12:24:07 +00:00
|
|
|
void flush(const std::function<void(const std::vector<WriteArea> &write_areas, size_t count)> &);
|
2016-11-16 04:31:32 +00:00
|
|
|
|
2016-12-04 01:47:19 +00:00
|
|
|
private:
|
2016-11-16 04:31:32 +00:00
|
|
|
// the buffer size
|
2016-11-16 15:13:06 +00:00
|
|
|
size_t bytes_per_pixel_;
|
2016-11-16 04:31:32 +00:00
|
|
|
|
|
|
|
// the buffer
|
2016-11-16 15:13:06 +00:00
|
|
|
std::vector<uint8_t> image_;
|
|
|
|
GLuint texture_name_;
|
2016-12-04 01:47:19 +00:00
|
|
|
|
2017-07-08 02:25:05 +00:00
|
|
|
// the current write area
|
|
|
|
WriteArea write_area_;
|
|
|
|
|
|
|
|
// the list of write areas that have ascended to the flush queue
|
2016-12-04 01:47:19 +00:00
|
|
|
std::vector<WriteArea> write_areas_;
|
|
|
|
size_t number_of_write_areas_;
|
2017-07-09 21:50:22 +00:00
|
|
|
bool is_full_, was_full_;
|
|
|
|
uint16_t first_unsubmitted_y_;
|
2016-12-06 12:24:07 +00:00
|
|
|
inline uint8_t *pointer_to_location(uint16_t x, uint16_t y);
|
|
|
|
|
|
|
|
// Usually: the start position for the current batch of write areas.
|
|
|
|
// Caveat: reset to the origin upon a submit. So used in comparison by flush to
|
|
|
|
// determine whether the current batch of write areas needs to be relocated.
|
2016-12-04 01:47:19 +00:00
|
|
|
uint16_t write_areas_start_x_, write_areas_start_y_;
|
2016-11-16 04:31:32 +00:00
|
|
|
};
|
|
|
|
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
2016-11-16 15:14:56 +00:00
|
|
|
#endif /* Outputs_CRT_Internals_TextureBuilder_hpp */
|