Ichthyostega
b804015cd7
These provide a faked context setup for unit testing. I created them ''out of sheer desperation'' several years ago, since it is impossible to verify the building blocks if you don't know what the building itself will look like. The recent design clean-up of OutputSlot has unfortunately removed a bunch of »hexagonal hooks« — and now I seem to be unable to hook into anything with my tests. Oh my!
295 lines
10 KiB
C++
295 lines
10 KiB
C++
/*
|
||
DUMMY-BUILDER-CONTEXT.hpp - fake simulated builder result for player tests
|
||
|
||
Copyright (C)
|
||
2011, Hermann Vosseler <Ichthyostega@web.de>
|
||
|
||
**Lumiera** is free software; you can redistribute it and/or modify it
|
||
under the terms of the GNU General Public License as published by the
|
||
Free Software Foundation; either version 2 of the License, or (at your
|
||
option) any later version. See the file COPYING for further details.
|
||
|
||
*/
|
||
|
||
/** @file dummy-builder-context.hpp
|
||
** Simulated result of a builder run for test purposes, without actual session and model content.
|
||
** Integration tests for the render engine or the player have to deal with a lot of prerequisites,
|
||
** since both an external environment and actual content form the Session is required to start any
|
||
** processing. Effectively the complete core application is required — while in fact the engine is
|
||
** built in an abstracted way and does not need to know much about the rest of the application.
|
||
** Thus, as a remedy, it is possible to establish a _faked context,_ exposing just those interfaces
|
||
** used by the engine for processing. As additional benefit, dedicated test operations can be rigged
|
||
** and verification routines can be used in place of actual media output.
|
||
**
|
||
** This faked builder context provides a selection of consistent media element IDs with sensible
|
||
** properties and type markers, plus the attachment points for a simulated model structure, as
|
||
** if generated from an actual session model by a real Builder run.
|
||
** - a set of ModelPort elements
|
||
** - a set of DataSink handles, as if an actual playback connection has been established
|
||
** @todo 5/2023 add more elements as needed for test driven integration of Player and engine
|
||
** @todo this was invented in 2012 -- as an act of desperation, since everything to build upon
|
||
** seemed to evade my grip. My hope at that time was so somehow _bootstrap_ an explorative
|
||
** design in order to get away from that top-down reasoning, that seemed to lead nowhere.
|
||
** However, work on the player had to be postponed to care for the GUI first; meanwhile
|
||
** I follow a similar idea, relying on »vertical integration slices«
|
||
** @deprecated 3/2026 not sure if we need this henceforth...
|
||
** It might be useful though in case we consider to build some kind of
|
||
** _component integration test_ -- yet for this to work, we'd need
|
||
** - a fake calculation
|
||
** - a fake OutputSlot
|
||
** @todo 5/2026 now I have beefed up the OutputSlot so that it can receive
|
||
** two feeds with an arbitrary number of frames. Still not sure if it's needed;
|
||
** however it should be noted that the MockDispatcher relies on the DummyPlayConnection,
|
||
** which in turn uses SimulatedBuilderContext, mostly to get _just some model ports_.
|
||
**
|
||
** @see mock-dispatcher.hpp
|
||
** @see JobPlanningPipeline_test
|
||
*/
|
||
|
||
|
||
#ifndef STEAM_PLAY_DUMMY_BUILDER_CONTEXT_H
|
||
#define STEAM_PLAY_DUMMY_BUILDER_CONTEXT_H
|
||
|
||
|
||
#include "lib/error.hpp"
|
||
#include "lib/format-string.hpp"
|
||
#include "steam/mobject/model-port.hpp"
|
||
#include "steam/fixture/model-port-registry.hpp"
|
||
#include "vault/out/output-slot-connection.hpp"
|
||
#include "steam/play/output-manager.hpp"
|
||
#include "steam/asset/timeline.hpp"
|
||
#include "steam/asset/pipe.hpp"
|
||
#include "vessel/query.hpp"
|
||
|
||
#include "lib/iter-explorer.hpp"
|
||
#include "lib/iter-source.hpp"
|
||
#include "lib/nocopy.hpp"
|
||
#include "lib/util.hpp"
|
||
|
||
#include <vector>
|
||
#include <deque>
|
||
#include <array>
|
||
|
||
|
||
namespace steam{
|
||
namespace play {
|
||
namespace test {
|
||
namespace err = lumiera::error;
|
||
|
||
using fixture::ModelPortRegistry;
|
||
using vault::mem::Buff;
|
||
using vault::mem::BuffHandle;
|
||
using vault::out::DataSink;
|
||
using vault::out::FrameID;
|
||
using lib::time::TimeValue;
|
||
using util::_Fmt;
|
||
|
||
|
||
|
||
|
||
/**
|
||
* A placeholder/dummy OutputSlot that captures all
|
||
* delivered output data into heap-allocated memory.
|
||
* @todo 5/2026 it can now be created and allocates a fixed layout
|
||
* of buffer storage, which implies it should not be copied
|
||
* and is thus used differently than a real OutputSlot;
|
||
* should reconsider what is actually needed here!
|
||
* @warning this used to be placeholder code, and now it was adapted
|
||
* to store frames, yet this new functionality is untested as of 5/2026
|
||
*/
|
||
struct FakeOutput
|
||
: OutputSlot
|
||
, util::NonCopyable
|
||
{
|
||
static constexpr uint NUM_FEEDS = 2;
|
||
static constexpr bool SINGLE_THREADED_TEST = true;
|
||
|
||
using DummyDat = uint64_t;
|
||
static constexpr size_t DUMMY_BUFF_SIZ = 1_KiB * sizeof(DummyDat);
|
||
|
||
using DummyBuff = std::array<DummyDat, DUMMY_BUFF_SIZ>;
|
||
using DummyBuffSeq = std::deque<DummyBuff>;
|
||
|
||
/**
|
||
* @todo 5/2026 quick-n-dirty placeholder code
|
||
* to expose some output buffers and provide
|
||
* the corresponding DataSink handles
|
||
*/
|
||
class DummyOutputConnection
|
||
: public vault::out::OutputSlot::Connection
|
||
{
|
||
DummyBuffSeq& buffers_;
|
||
|
||
size_t getBufferSize() const override { return DUMMY_BUFF_SIZ; }
|
||
Buff* claimBufferFor (FrameID) override;
|
||
void publish (Buff*) override { /* fake "publish buffer content" */ }
|
||
void release (Buff*) override { /* fake "complete buffer cycle" */ }
|
||
void shutDown () override { /* fake "shutDown() Connection" */ }
|
||
|
||
public:
|
||
~DummyOutputConnection();
|
||
DummyOutputConnection (DummyBuffSeq& buffers)
|
||
: buffers_{buffers}
|
||
{ }
|
||
// OutputSlot::Connection is non-copyable
|
||
};
|
||
|
||
using Connections = lib::ScopedCollection<DummyOutputConnection>;
|
||
using MockConnectState = OutputSlot::AllocState<DummyOutputConnection, SINGLE_THREADED_TEST>;
|
||
|
||
using OutBuffs = std::array<DummyBuffSeq, NUM_FEEDS>;
|
||
OutBuffs buffers_{};
|
||
|
||
FakeOutput()
|
||
: OutputSlot{std::make_unique<MockConnectState> (NUM_FEEDS
|
||
,[&,i=0](auto& storage) mutable
|
||
{
|
||
storage.template create<DummyOutputConnection> (buffers_[i++]);
|
||
})}
|
||
{ }
|
||
};
|
||
|
||
inline Buff*
|
||
FakeOutput::DummyOutputConnection::claimBufferFor (FrameID fra)
|
||
{
|
||
REQUIRE (fra >= 0);
|
||
if (uint64_t(fra) >= buffers_.size())
|
||
buffers_.resize(fra+10);
|
||
return reinterpret_cast<Buff*> (& buffers_[fra]);
|
||
}
|
||
|
||
|
||
using asset::Pipe;
|
||
using asset::PPipe;
|
||
using asset::Struct;
|
||
using asset::Timeline;
|
||
using asset::PTimeline;
|
||
using mobject::ModelPort;
|
||
using fixture::ModelPortRegistry;
|
||
using util::contains;
|
||
using vessel::Query;
|
||
|
||
|
||
using PID = asset::ID<Pipe>;
|
||
using TID = asset::ID<Struct>;
|
||
|
||
using ModelPorts = lib::IterSource<mobject::ModelPort>::iterator;
|
||
using DummyOutputLink = std::pair<mobject::ModelPort, DataSink>;
|
||
|
||
|
||
inline PID
|
||
getPipe (string id)
|
||
{
|
||
return Pipe::query ("id("+id+")");
|
||
}
|
||
|
||
inline TID
|
||
getTimeline (string id)
|
||
{
|
||
return asset::Struct::retrieve (Query<Timeline> ("id("+id+")"))->getID();
|
||
}
|
||
|
||
const uint NUMBER_OF_PORTS = 2;
|
||
const string namePortA("bus-A");
|
||
const string namePortB("bus-B");
|
||
|
||
/**
|
||
* helper for dummy render engine:
|
||
* Simulate the result of a build process,
|
||
* without actually running the builder.
|
||
* Produces some mock pipes, model ports etc.
|
||
*/
|
||
struct SimulatedBuilderContext
|
||
{
|
||
ModelPortRegistry registry_;
|
||
ModelPortRegistry* existingRegistry_;
|
||
|
||
std::vector<ModelPort> modelPorts_;
|
||
std::vector<DataSink> dataSinks_;
|
||
|
||
FakeOutput fakeOutput_;
|
||
|
||
/** setup */
|
||
SimulatedBuilderContext()
|
||
: registry_()
|
||
, existingRegistry_(ModelPortRegistry::setActiveInstance (registry_))
|
||
{
|
||
performMockBuild();
|
||
}
|
||
|
||
/** tear-down */
|
||
~SimulatedBuilderContext()
|
||
{
|
||
if (existingRegistry_)
|
||
ModelPortRegistry::setActiveInstance (*existingRegistry_);
|
||
else
|
||
ModelPortRegistry::shutdown();
|
||
}
|
||
|
||
void
|
||
performMockBuild()
|
||
{
|
||
PID pipeA = getPipe (namePortA);
|
||
PID pipeB = getPipe (namePortB);
|
||
TID someTimeline = getTimeline ("dummy_Timeline");
|
||
|
||
// start out with defining some new model ports......
|
||
registry_.definePort (pipeA, someTimeline);
|
||
registry_.definePort (pipeB, someTimeline);
|
||
|
||
registry_.commit();
|
||
|
||
// now "bus-A" and "bus-B" are known as model ports
|
||
modelPorts_.push_back (ModelPort(pipeA));
|
||
modelPorts_.push_back (ModelPort(pipeB));
|
||
|
||
// prepare corresponding placeholder DataSink (a fake active output connection)
|
||
dataSinks_.clear();
|
||
lib::explore(fakeOutput_.getOpenedSinks())
|
||
.effuse (dataSinks_);
|
||
}
|
||
|
||
|
||
ModelPorts
|
||
getAllModelPorts()
|
||
{
|
||
return lib::iter_source::eachEntry (modelPorts_.begin(), modelPorts_.end());
|
||
}
|
||
|
||
DummyOutputLink
|
||
getModelPort (uint index)
|
||
{
|
||
REQUIRE (index < modelPorts_.size());
|
||
return {modelPorts_[index]
|
||
,dataSinks_[index]
|
||
};
|
||
}
|
||
|
||
/**
|
||
* Access a generated output frame.
|
||
* @remark FakeOutput maintains Deque-Storage for each feed.
|
||
* @tparam X data type to assume as content of the frame (only checked for size)
|
||
* @param feed number of the output feed to access
|
||
* @param frame frame numer within the output feed
|
||
*/
|
||
template<typename X>
|
||
X&
|
||
accessOutputBufferAs (uint feed, FrameID frame)
|
||
{
|
||
static_assert (sizeof(X) <= FakeOutput::DUMMY_BUFF_SIZ
|
||
,"desired data type would not fit into FakeOutput buffer");
|
||
if (feed >= FakeOutput::NUM_FEEDS)
|
||
throw err::Invalid{_Fmt{"Feed #%i > %i allowed"}
|
||
% feed % (FakeOutput::NUM_FEEDS-1)};
|
||
|
||
auto availFrames = fakeOutput_.buffers_[feed].size();
|
||
if (frame >= availFrames)
|
||
throw err::Invalid{_Fmt{"Frame #%02i > %02i available frames"}
|
||
% frame % availFrames};
|
||
|
||
return reinterpret_cast<X&> (fakeOutput_.buffers_[feed][frame]);
|
||
}
|
||
};
|
||
|
||
}}} // namespace steam::play::test
|
||
#endif /*STEAM_PLAY_DUMMY_BUILDER_CONTEXT_H*/
|