jepler/povray
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity
povray/vfe/vfesession.h
chris20 86f4639d37 Initial import
2013-11-06 13:07:19 -05:00

1279 lines
69 KiB
C++
Raw Permalink Blame History

/*******************************************************************************
* vfesession.h
*
* This file contains declarations relating to the vfe session management class.
*
* Author: Christopher J. Cason
*
* ---------------------------------------------------------------------------
* Persistence of Vision Ray Tracer ('POV-Ray') version 3.7.
* Copyright 1991-2013 Persistence of Vision Raytracer Pty. Ltd.
*
* POV-Ray is free software: you can redistribute it and/or modify
* it under the terms of the GNU Affero General Public License as
* published by the Free Software Foundation, either version 3 of the
* License, or (at your option) any later version.
*
* POV-Ray is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU Affero General Public License for more details.
*
* You should have received a copy of the GNU Affero General Public License
* along with this program. If not, see <http://www.gnu.org/licenses/>.
* ---------------------------------------------------------------------------
* POV-Ray is based on the popular DKB raytracer version 2.12.
* DKBTrace was originally written by David K. Buck.
* DKBTrace Ver 2.0-2.12 were written by David K. Buck & Aaron A. Collins.
* ---------------------------------------------------------------------------
* $File: //depot/public/povray/3.x/vfe/vfesession.h $
* $Revision: #1 $
* $Change: 6069 $
* $DateTime: 2013/11/06 11:59:40 $
* $Author: chrisc $
*******************************************************************************/
#ifndef __VFESESSION_H__
#define __VFESESSION_H__
#include <queue>
#include "base/image/colourspace.h"
namespace vfe
{
using namespace pov_frontend;
using namespace pov_base;
////////////////////////////////////////////////////////////////////////////
// class IOPath
//
// IOPaths are used to keep track of IO Restrictions. Each instance of the
// class will contain information regarding a path and its attributes (e.g.
// if it's recursive or not). The class by itself doesn't identify if the
// path is a permitted or excluded one - this is determined by the collection
// to which the instance belongs.
class IOPath
{
public:
// construct an IOPath given an existing Path and a recursion flag.
IOPath(const Path& path, bool recursive) : m_Path(path), m_Recursive(recursive) {}
// construct an IOPath given a std::string path and a recursion flag.
IOPath(const string& path, bool recursive) : m_Path(Path(ASCIItoUCS2String(path.c_str()))), m_Recursive(recursive) {}
// construct an IOPath given a UCS2String Path and a recursion flag.
IOPath(const UCS2String& path, bool recursive) : m_Path(path), m_Recursive(recursive) {}
virtual ~IOPath() {}
// returns true if paths below the given path are considered to be included
// in consideration of an IO restriction.
bool IsRecursive() const { return m_Recursive; }
// return the stored path as an instance of the pov_base::Path class.
const Path& GetPath() const { return m_Path; }
private:
bool m_Recursive;
Path m_Path;
} ;
// convenience typedefs.
typedef vector<string> StringVector;
typedef vector<UCS2String> UCS2StringVector;
typedef vector<IOPath> IOPathVector;
class vfeDisplay;
class VirtualFrontEnd;
////////////////////////////////////////////////////////////////////////////
// class vfeDestInfo
//
// Currently unused, destined to hold information regarding the destination
// of a remote session attempt.
class vfeDestInfo
{
} ;
////////////////////////////////////////////////////////////////////////////
// class vfeAuthInfo
//
// Currently unused, destined to hold information regarding authentication
// when making a remote session open request.
class vfeAuthInfo
{
} ;
////////////////////////////////////////////////////////////////////////////
// class vfeRenderOptions
//
// This class is used to hold information regarding a pending render request.
// For example, the library paths, source file, output file, and really
// anything else that could vary from render to render.
class vfeRenderOptions
{
friend class vfeSession;
public:
// Construct an instance of vfeRenderOptions. the thread count defaults
// to 2.
vfeRenderOptions() : m_ThreadCount(2) {}
virtual ~vfeRenderOptions() {}
// Clear the set options. This includes library paths, INI files,
// commands, the source file, the thread count (defaults back to 2),
// and all other options set in the kPOVObjectClass_RenderOptions object.
void Clear()
{
ClearLibraryPaths();
ClearINIs();
ClearCommands();
m_SourceFile.clear();
m_ThreadCount = 2;
POVMSObject obj;
POVMSObject_New (&obj, kPOVObjectClass_RenderOptions);
m_Options = POVMS_Object(obj);
}
// Clear any library paths that have been added.
void ClearLibraryPaths() { m_LibraryPaths.clear(); }
// Add a library path given a std::string.
void AddLibraryPath(const string& Path) { m_LibraryPaths.push_back(ASCIItoUCS2String(Path.c_str())); }
// Add a library path given a UCS2String.
void AddLibraryPath(const UCS2String& Path) { m_LibraryPaths.push_back(Path); }
// Get the current library paths as a vector of UCS2 strings.
// The returned paths are a const reference.
const UCS2StringVector& GetLibraryPaths() const { return m_LibraryPaths; }
// Get the current library paths as a vector of UCS2 strings.
// The returned paths are a copy of the internal paths.
UCS2StringVector GetLibraryPaths() { return m_LibraryPaths; }
// Set the source file to be parsed (must be an SDL file, INI not
// permitted). The file is specified as a UCS2String full or relative
// path, with optional extension.
void SetSourceFile(const UCS2String& File) { m_SourceFile = File; }
// Set the source file to be parsed (must be an SDL file, INI not
// permitted). The file is specified as a std::string full or relative
// path, with optional extension.
void SetSourceFile(const string& File) { m_SourceFile = ASCIItoUCS2String(File.c_str()); }
// Returns a const reference to the currently set source file (may be
// an empty string). Return type is a const reference to a UCS2String.
const UCS2String& GetSourceFile() const { return m_SourceFile; }
// Clears the list of INI files.
void ClearINIs() { m_IniFiles.clear() ; }
// Adds the supplied std::string to the list of INI files to be read
// prior to the start of the render. The files are processed in the
// order in which they are added to this list.
void AddINI(const string& File) { m_IniFiles.push_back(ASCIItoUCS2String(File.c_str())); }
// Adds the supplied UCS2String to the list of INI files to be read
// prior to the start of the render. The files are processed in the
// order in which they are added to this list.
void AddINI(const UCS2String& File) { m_IniFiles.push_back(File); }
// Returns a const UCS2StringVector reference containing the
// list of INI files to be processed, in order first to last.
const UCS2StringVector& GetINIs() const { return m_IniFiles; }
// Returns a UCS2StringVector copy of the list of INI files to be
// processed, in order first to last.
UCS2StringVector GetINIs() { return m_IniFiles; }
// Sets the number of threads to be used for rendering (and potentially
// for bounding and similar tasks, if this is supported in the future).
// Clipped to the range 1..512.
void SetThreadCount(int Count) { m_ThreadCount = max(1, min(Count, 512)); }
// Gets the number of threads currently set to be used for renders.
// Defaults to 2.
int GetThreadCount() const { return m_ThreadCount; }
// Clears any commands set via the AddCommand() method.
void ClearCommands() { m_Commands.clear(); }
// Adds the supplied std::string to the list of commands to be handled
// prior to the start of any render. The commands are processed in the
// order in which they appear in this list. A 'command' in this context
// is basically anything that could normally appear on the command-line
// of a POV-Ray console compile.
void AddCommand(const string& Command) { m_Commands.push_back(Command); }
// Returns a const reference to a vector<std::string> containing the
// current list of commands as added by AddCommand(), in order first
// to last.
const StringVector& GetCommands() const { return m_Commands; }
// Returns a copy of the vector<std::string> which holds the current
// list of commands as added by AddCommand(), in order first to last.
StringVector GetCommands() { return m_Commands; }
// Returns a non-const reference to the current POVMS_Object options
// instance.
POVMS_Object& GetOptions() { return m_Options; }
protected:
int m_ThreadCount;
UCS2StringVector m_IniFiles;
UCS2StringVector m_LibraryPaths;
StringVector m_Commands;
UCS2String m_SourceFile;
POVMS_Object m_Options;
} ;
// The integer values which may be returned from any of the VFE methods
// which return error codes.
enum
{
vfeNoError = 0,
vfeNoInputFile = 1024, // "No input file provided"
vfeRenderBlockSizeTooSmall, // "Specified block size is too small"
vfeFailedToWriteINI, // "Failed to write output INI file"
vfeFailedToSetSource, // "Failed to set source file"
vfeFailedToParseINI, // "Failed to parse INI file"
vfeIORestrictionDeny, // "I/O Restrictions prohibit access to file"
vfeFailedToParseCommand, // "Failed to parse command-line option"
vfeFailedToSetMaxThreads, // "Failed to set number of render threads"
vfeFailedToSendRenderStart, // "Failed to send render start request"
vfeRenderOptionsNotSet, // "Render options not set, cannot start render"
vfeAlreadyStopping, // "Renderer is already stopping"
vfeNotRunning, // "Renderer is not running"
vfeInvalidParameter, // "Something broke but we're not sure what"
vfeSessionExists, // "Only one session at once permitted in this version"
vfePOVMSInitFailed, // "Failed to initialize local messaging subsystem"
vfeOpenContextFailed, // "Failed to open context with core messaging subsystem"
vfeConnectFailed, // "Failed to connect to core messaging subsystem"
vfeInitializeTimedOut, // "Timed out waiting for worker thread startup"
vfeRequestTimedOut, // "Timed out waiting for request to be serviced"
vfeFailedToInitObject, // "Failed to initialize internal options storage"
vfeCaughtException, // "Caught exception of unexpected type"
vfeCaughtCriticalError, // "Caught critical error"
vfeDisplayGammaTooSmall, // "Specified display gamma is too small"
vfeFileGammaTooSmall, // "Specified file gamma is too small"
vfeUnsupportedOptionCombination, // "Unsupported option combination"
} ;
// The status flags (and mask combinations of flags) which may be returned
// from vfeSession::GetStatus(), or passed to vfeSession::SetEventMask().
enum
{
stNone = 0x00000000, // No status to report
stClear = 0x00000001, // vfeSession::Clear() has been called
stReset = 0x00000002, // vfeSession::Reset() has been called
stFailed = 0x00000004, // Render failed
stSucceeded = 0x00000008, // Render succeeded
stStatusMessagesCleared = 0x00000010, // vfeSession::ClearStatusMessages() called
stOutputFilenameKnown = 0x00000020, // vfeSession::AdviseOutputFilename() called
stRenderingAnimation = 0x00000040, // vfeSession::SetRenderingAnimation() called
stAnimationFrameCompleted = 0x00000080, // vfeSession::AdviseFrameCompleted() called
stStreamMessage = 0x00000100, // One or more stream messages are available
stErrorMessage = 0x00000200, // One or more error messages are available
stWarningMessage = 0x00000400, // One or more warning messages are available
stStatusMessage = 0x00000800, // One or more status messages are available
stAnyMessage = 0x00000f00, // A mask of stStream, Error, Warning, and Status message flags.
stAnimationStatus = 0x00001000, // An animation status update is available
stBackendStateChanged = 0x00002000, // The state of the backend (reflected in pov_frontend::State) has changed
stRenderStartup = 0x00004000, // The render engine has started up
stRenderShutdown = 0x00008000, // The render engine has shut down
stShutdown = 0x10000000, // The session is shutting down
stCriticalError = 0x20000000, // A critical error (exception, POVMS memory alloc failure, etc) has occurred
stNoIgnore = 0x30000000, // A mask containing the status flags which can't be masked off
stNoClear = 0x30000000, // A mask containing the status flags which aren't cleared after a call to vfeSession::GetStatus()
} ;
// Used internally to track pause/resume status.
typedef enum
{
rqNoRequest = 0,
rqPauseRequest = 1,
rqResumeRequest = 2
} rqRequest;
// The data type returned by vfeSession::GetStatus().
typedef int vfeStatusFlags ;
////////////////////////////////////////////////////////////////////////////
// class vfeSession (vfe is short for Virtual FrontEnd).
//
// This class is the core of VFE. Each instance of a vfeSession represents
// a connection to the messaging subsystem of the POV-Ray backend, either
// locally or (in the future) remotely. It has a worker thread to handle
// communication with the backend asynchronously from the client (the
// software which created the session instance), and provides status
// feedback via either polling of the GetStatus() method, or via timed
// waits (again via GetStatus(), but this time using a timeout and an
// event notification system).
//
// Additionally vfeSession provides numerous convenience methods for
// setting up renders, monitoring renders (including retrieving status
// messages and render state), and associated maintenance such as the
// setting and retrieval of IO restrictions, display management, and
// critical event notifications.
//
// Some methods of vfeSession are pure virtual; it is required that each
// platform derive its own version in order to provide platform-specific
// functionality. Currently there are only six methods that must be provided
// in this way, summarized below:
//
// GetTemporaryPath() // return the path to a temporary storage area
// CreateTemporaryFile() // create a temporary filename (but don't open it)
// DeleteTemporaryFile() // delete a temporary file previously created
// GetTimestamp() // return a 64-bit one-millisecond resolution timestamp
// NotifyCriticalError() // asynchronously notify user of a critical error
// RequestNewOutputPath() // ask user for new output path if attempt to write file fails
//
// As can be seen, most of the above are trivial and in fact three of them
// already exist in pre-v3.7 platform-specific code. Refer to the windows
// reference implementation in vfe/win/ for well-commented examples of the
// implementation of the above mandatory methods, as well as a number of
// other optional ones.
class vfeSession
{
friend class vfeConsole;
friend class vfeParserMessageHandler;
friend class vfeRenderMessageHandler;
friend class vfeProcessRenderOptions;
friend class vfeDisplay;
friend class VirtualFrontEnd;
public:
// Our DisplayCreator functor - see vfeSession::SetDisplayCreator().
typedef boost::function<vfeDisplay *(unsigned int, unsigned int, GammaCurvePtr, vfeSession *session, bool)> DisplayCreator;
typedef enum
{
mUnclassified = 0,
mDebug,
mInformation,
mWarning,
mPossibleError,
mError,
mAnimationStatus,
mGenericStatus,
mDivider
} MessageType ;
////////////////////////////////////////////////////////////////////////
// class MessageBase.
//
// MessageBase encapsulates the various types of messages that may be
// returned from the base POV-Ray code. Each message has associated with
// it the ID of the session which generated it, a timestamp, and a type.
// The message itself is stored as a std::string. This base class is
// specialized into several more specific message types.
class MessageBase
{
public:
MessageBase(const vfeSession& session) :
m_Id(session.GetID()), m_TimeStamp (session.GetTimestamp()), m_Type(mUnclassified) {}
MessageBase(const vfeSession& session, MessageType type, string msg = "") :
m_Id(session.GetID()), m_TimeStamp (session.GetTimestamp()), m_Type(type), m_Message(msg) {}
virtual ~MessageBase() {}
POV_LONG m_TimeStamp;
MessageType m_Type;
string m_Message;
int m_Id;
} ;
////////////////////////////////////////////////////////////////////////
// class GenericMessage.
//
// GenericMessage builds on MessageBase by further providing the line,
// column, and filename of the SDL which caused the message generation.
class GenericMessage : public MessageBase
{
public:
GenericMessage(const vfeSession& session) :
MessageBase(session), m_Line(0), m_Col(0) {}
GenericMessage(const vfeSession& session, MessageType type, string msg, const UCS2String file = UCS2String(), int line = 0, int col = 0) :
MessageBase (session, type, msg), m_Filename(file), m_Line(line), m_Col(col) {}
virtual ~GenericMessage() {}
int m_Line;
int m_Col;
UCS2String m_Filename;
} ;
////////////////////////////////////////////////////////////////////////
// class StatusMessage.
//
// StatusMessage builds on MessageBase to encapsulate the messages that
// are generated by the core code during processing of a scene. This
// includes anything from parse status all the way through to final
// render stats. It has an optional delay member which is set by the
// vfe code to suggest to the client that after displaying the current
// message (the one the delay is retrieved with), it may like to delay
// that many milliseconds before erasing it and displaying the next.
// (This is of course only relevent for temporary display locations,
// such as in the status bar of a UI-based client implementation).
class StatusMessage : public MessageBase
{
public:
StatusMessage(const vfeSession& session) :
MessageBase(session), m_Delay(0), m_Frame(0), m_TotalFrames(0) {}
StatusMessage(const vfeSession& session, string msg, int m_Delay) :
MessageBase(session, mGenericStatus, msg), m_Delay(m_Delay), m_Frame(0), m_TotalFrames(0) {}
StatusMessage(const vfeSession& session, const UCS2String& file, int frame, int totalframes) :
MessageBase(session, mAnimationStatus), m_Delay(0), m_Filename(file), m_Frame(frame), m_TotalFrames(totalframes) {}
virtual ~StatusMessage() {}
int m_Delay;
int m_Frame;
int m_TotalFrames;
UCS2String m_Filename;
} ;
// The following queues are used to hold messages collected from the
// core code via vfeSession's worker thread.
typedef std::queue<GenericMessage> GenericQueue;
typedef std::queue<StatusMessage> StatusQueue;
typedef std::queue<MessageBase> ConsoleQueue;
// Construct a new instance of a vfeSession. An optional ID may be
// provided (which defaults to 0 if not). This ID is opaque to the
// VFE code itself - it only has meaning to the client software. It
// can be used to differentiate between sessions in a multiple-
// session implementation. If you are not implementing such a client
// it is sufficient to leave it at the default value.
vfeSession(int id = 0);
virtual ~vfeSession();
// Convenience method to ensure the frontend connection (an internal
// concept representing the connection between VFE and the POV-Ray
// internal code) was created successfully. It will throw an exception
// of type pov_base::Exception if the connection does not exist.
void CheckFrontend() const { if (m_Frontend == NULL) throw POV_EXCEPTION_STRING("Frontend not connected"); }
// Clears many of the internal state information held by VFE regarding
// a render. Typically called before starting a new render. Included in
// the clear are the failure/success status, cancel request state,
// error code, percent complete, number of pixels rendered, total pixels
// in render, current animation frame, and total animation frame count.
// If the optional Notify flag is set (defaults to true), a status event
// of type stClear is generated. Note that this method does not empty the
// message queues (see Reset() for that).
virtual void Clear(bool Notify = true);
// Resets a session - this not only does the same work as vfeSession::Clear
// (without a stClear notification) but it also empties all the message
// queues, clears the input and output filenames, clears any animation
// status information, resets the status flags and clears the event mask.
// It will then generate a stReset notification.
virtual void Reset();
// Clears all messages from the status message queue.
virtual void ClearStatusMessages();
// Returns true if a fatal error message has been received since the
// last call to vfeSession::Clear(). Note that in the context of VFE
// only errors that will halt a render request are considered 'fatal'.
virtual bool HadErrorMessage() const { return m_HadErrorMessage; }
// Return true if the render is considered to have succeeded. In the
// case of an animation, this relates to all requested frames being
// processed, not each individual frame. The client is generally
// notified of render completion via the status event notification
// system, and then calls this method to find out the result.
virtual bool Succeeded() const { return m_BackendThreadExited == false && m_Succeeded; }
// The converse of vfeSession::Succeeded(), with the caveat that it
// will be set upon the failure of any frame in an animation, not that
// of all frames.
virtual bool Failed() const { return m_Failed; }
// Used to set up a session with a POV backend. Accepts two
// parameters - a destination (vfeDestInfo) and authorization
// (vfeAuthInfo), both pointers. Currently these must be NULL.
//
// Intialize() will call the Reset() method, and then create
// the session's worker thread, at which time it will wait on
// an event for the worker thread to signal that it has completed
// its own initialization. By default the worker thread setup is
// considered to have failed if it has not signalled within three
// seconds (elapsed time). However to aid debugging this is extended
// to 123 seconds if _DEBUG is defined.
//
// If the startup is successful, this method returns vfeNoError after
// issuing a stBackendStateChanged status notification. Otherwise it
// will either set m_LastError to vfeInitializeTimeout and return that
// same value, or it will retrieve the error code set by the worker
// thread, wait for the worker thread to exit, and return that code.
//
// The worker thread itself is responsible for creating the actual
// connection with the backend code.
virtual int Initialize(vfeDestInfo *Dest, vfeAuthInfo *Auth);
// Returns the ID passed to the class constructor. Defaults to 0 if not specified.
virtual int GetID() const { return m_Id ; }
// Returns a copy of the shared pointer containing the current instance
// of a pov_frontend::Display-derived render preview instance, which may
// be NULL.
virtual boost::shared_ptr<Display> GetDisplay() const;
// If a VFE implementation has provided a display creator functor via
// vfeSession::SetDisplayCreator(), this method will call it with the
// width, height, gamma factor, and default visibility flag of the requested
// render preview window. Otherwise it will return whatever the default display
// creator returns (see SetDisplayCreator()).
//
// It is called when the core POV-Ray code requests that a render preview
// window be created. The display instance returned is expected to conform
// to the definition of the pov_frontend::Display class (but it typically
// a platform-specific derivative of that.)
virtual vfeDisplay *CreateDisplay(unsigned int width, unsigned int height, GammaCurvePtr gamma, bool visible = false);
// Used by VFE implementations to allow their own custom pov_frontend::Display
// derived render preview window class to be created when the main POV-Ray code
// wants a preview window. The passed parameter is a DisplayCreator (see the
// typedef earlier on in vfeSession and the example in CreateFrontend() and
// WinDisplayCreator() of source/windows/pvfrontend.cpp).
//
// If this method is not called, the display creator defaults to
// vfeSession::DefaultDisplayCreator().
virtual void SetDisplayCreator(DisplayCreator creator) { m_DisplayCreator = creator; }
// Returns a pointer to the internal VirtualFrontendInstance used by the session.
// Generally a client should not need this - if there is some good reason to get
// at the frontend, it probably means that there is functionality missing from
// vfeFrontend (which, after all, is intended to wrap the actual frontend).
virtual VirtualFrontEnd *GetFrontend() const { return m_Frontend ; }
// This method returns the current set of status flags as set by the worker
// thread and various other parts of vfeSession. The status flags returned
// are not affected by any event mask set (see vfeSession::SetEventMask()
// for more information), but whether or not a wait occurs.
//
// Two parameters are accepted (both optional). The first one, a bool,
// determines whether or not the internal copy of the status flags is
// cleared prior to returning. By default, this is the case. Note that
// flags identified by the stNoClear mask cannot be cleared by this method
// and will remain set until vfeSession::Reset() is called. See the definition
// of the status flags enum in vfesession.h for more information on flags.
// Note that even if the flags are cleared, an stClear notification does not
// get set.
//
// The second parameter - an int - sets the wait time. If not specified, it
// defaults to -1, which means wait indefinitely for an event. If set to 0,
// it effectively turns this method into a status polling function, since
// there will never be a wait. Otherwise the parameter specifies the maximum
// number of milliseconds to wait on the status notification event before
// returning the status flags (note that there is no indication of timeout).
//
// Typical usage of this method by a client that has its own status handling
// thread would be for the thread to call this method with an indefinite
// timeout, and depend on the stShutdown event and status notification to
// determine if its host application wants it to exit. stShutdown events can
// be generated by the host calling vfeSession::Shutdown() (it is safe for
// this to be called from any thread multiple times).
//
// A client that does not want to devote a thread to status processing
// would typically call this method in polling mode, with perhaps a short
// timeout, depending on the implementation. (The sample console example
// provided for VFE does this).
virtual vfeStatusFlags GetStatus(bool Clear = true, int WaitTime = -1) ;
// This method allows a client to specify a set of status flags that it
// wants to allow to generate events. An 'event' in terms of VFE is the
// case where an action (typically that of the worker thread) occurs that
// would set, in the internal status flags, a status indication that is
// not otherwise masked out by a call to this method. The net result of
// an event being generated is that a thread waiting via a call to the
// vfeSession::GetStatus() method with a non-zero timeout will get woken
// up immediately. Note that this will occur even if the flag is already
// set in the internal flags (e.g. GetStatus() was called with clear set
// to false). Note also that if more than one client thread has called
// GetStatus() and is sleeping on an event, only one will be woken.
//
// By default, all events are allowed (this is as if SetEventMask() had
// been called with a parameter of ~stNone).
//
// Be aware that some events may not be masked out (e.g. stShutdown,
// stCriticalError). See the definition of the status flags for more
// detail.
virtual void SetEventMask(vfeStatusFlags Mask = stNone) { m_EventMask = vfeStatusFlags (Mask | stNoIgnore); }
// Returns the current event mask (see vfeSession::SetEventMask()).
virtual vfeStatusFlags GetEventMask() const { return vfeStatusFlags(m_EventMask); }
// Returns true if the POV-Ray code is in a state where a pause request
// both makes sense and can be accepted. Typical use of this method is
// to call it each time a stBackendStateChanged event occurs, and to use
// the returned value to configure a client user interface (e.g. to gray
// out or enable a pause button or menu item).
//
// Throws a pov_base::Exception if the frontend does not exist (i.e.
// vfeSession::Initialize() hasn't been called or failed when called).
virtual bool IsPausable() const;
// Used similarly to vfeFrontend::IsPausable(), but returns the actual
// pause/not paused state.
//
// Throws a pov_base::Exception if the frontend does not exist (i.e.
// vfeSession::Initialize() hasn't been called or failed when called).
virtual bool Paused() const;
// Requests the POV-Ray backend code to pause whatever it is doing by entering
// an idle loop with calls to pov_base::Delay(). This method is synchronous
// and thus a delay of up to three seconds can occur waiting for the backend
// to respond. If a timeout occurs, m_LastError is set to vfeRequestTimedOut
// and this method returns false. Otherwise, m_LastError is set to vfeNoError
// and the return value is set according to whether the backend accepted the
// request (true) or rejected it (false). Typically it will only reject a
// pause request if it is not in a pausable state (e.g. it's not rendering).
//
// Implementation note: the pause request itself is actually proxied via the
// session's worker thread, since the POV-Ray messaging system requires that
// all such requests come from the thread that created the session (this is
// to allow internal dispatching of message replies to the right place). The
// net effect of this is that the worker thread won't be doing anything else
// (such as dispatching messages) once it starts processing this request.
//
// Throws a pov_base::Exception if the frontend does not exist (i.e.
// vfeSession::Initialize() hasn't been called or failed when called).
virtual bool Pause();
// If called with on == true, tells POV-Ray to pause rendering after the end
// of each frame of an animation (but has no effect on non-animation renders).
// This is almost the same as calling Pause() at the right time, but without
// the timing constraints associated with that (for fast renders, the next
// frame could have started before the frontend's pause request was processed).
// The pause is not applied after the last frame.
//
// Note that the neither the rendering engine nor the parser are actually
// paused (in the usual sense of the word) by this feature; the implementation
// simply does not start the next frame after one ends.
//
// A render can be resumed by calling Resume() as per normal.
//
// Internally, this option defaults to false, and is reset whenever Clear()
// or Reset() is called.
virtual void PauseWhenDone(bool on) { m_PauseWhenDone = on; }
// get the current pause when done setting.
virtual bool GetPauseWhenDone(void) { return m_PauseWhenDone; }
// The converse of vfeSession::Pause(). All the same considerations apply.
virtual bool Resume();
// Returns true if an animation is being rendered. The result can only
// be considered valid if the render has actually been started.
virtual bool RenderingAnimation() const { return m_RenderingAnimation; }
// Returns the current frame of an animation. Only valid once the internal
// state has reached kStarting (see the stBackendStateChanged status flag).
// The typical way of reading this is to wait for a stAnimationStatus event
// and then call GetCurrentFrame().
virtual int GetCurrentFrame() const { return m_CurrentFrame; }
// Returns the total frame count of an animation. Valid once the internal
// state has reached kStatring. The typical way of reading this is to wait
// for a stAnimationStatus flag and then call GetTotalFrames().
virtual int GetTotalFrames() const { return m_TotalFrames; }
// Returns the percentage of the render that has completed, in terms of
// pixel count, as an int in the range 0 to 100. The internal code that
// updates this value does so in response to a progress message from
// the backend, and since this also generates a status message, your
// status message handling code is a good place to call this method from.
virtual int GetPercentComplete() const { return m_PercentComplete; }
// Returns count of pixels rendered. Same consideration for update
// applies as does for vfeSession::GetPercentComplete().
virtual int GetPixelsRendered() const { return m_PixelsRendered; }
// Returns total pixel count. This value is only valid once at least
// one render progress message has been received from the backend.
virtual int GetTotalPixels() const { return m_TotalPixels; }
////////////////////////////////////////////////////////////////////////
// Return an absolute path including trailing path separator.
// *nix platforms might want to just return "/tmp/" here.
// NB this method is pure virtual.
virtual UCS2String GetTemporaryPath(void) const = 0;
////////////////////////////////////////////////////////////////////////
// Return a valid and unique temporary filename.
// NB this method is pure virtual.
virtual UCS2String CreateTemporaryFile(void) const = 0;
////////////////////////////////////////////////////////////////////////
// Delete the filename passed. Platforms may like to check that the file
// specified lies either in a valid temporary path location or is a valid
// temporary filename (see e.g. vfeSession::GetTemporaryPath()).
// NB this method is pure virtual.
virtual void DeleteTemporaryFile(const UCS2String& filename) const = 0;
////////////////////////////////////////////////////////////////////////
// Return a timestamp to be used internally for queue sorting etc. The
// value returned must be 64-bit and in milliseconds; the origin of the
// count is not important (e.g. milliseconds since 1/1/1970, or whatever
// it doesn't matter), as long as it is consistent value (milliseconds
// since system boot is NOT a valid value since it will change each boot).
// Also please don't call time() and multiply by 1000 since vfe wants at
// least 100ms precision (so it can do sub-one-second event timing).
//
// It's also important that the count not go backwards during the life
// of a vfeSession instance; this means you should attempt to detect wall
// clock changes by caching the last value your implementation returns
// and adding an appropriate offset if you calculate a lower value later
// in the session.
//
// NB this method is pure virtual.
virtual POV_LONG GetTimestamp(void) const = 0;
/////////////////////////////////////////////////////////////////////////
// This method will get called on POVMS critical errors (e.g. cannot
// allocate memory, amongst other things). Note that you should not
// assume that you can e.g. allocate memory when processing this call.
//
// Before calling this function vfe sets a flag that prevents the worker
// thread from processing any more messages; it will wait for you to
// call Shutdown(). Your UI thread can find out if this method has been
// called by checking for the presence of the stCriticalError status bit
// returned from vfeSession::GetStatus() (note that this bit is not
// necessarily already set at the time the method is called though).
//
// If you are running a genuine virtual frontend (e.g. stateless HTTP
// interface), we may want to set a flag to display the message later
// rather than pop up a messagebox on the local windowstation. Otherwise
// you would probably display the message immediately.
virtual void NotifyCriticalError(const char *message, const char *file, int line) = 0;
// This method causes a shutdown of the vfeSession instance. Specifically
// it will set a flag asking the worker thread to exit, issue a
// stShutdown notification, and then wait for the worker thread to exit.
// The optional boolean parameter (default false) is used by the caller
// to indicate a forced shutdown of the worker thread is permissible
// (e.g. a kill if it doesn't shutdown gracefully within a reasonable
// period of time). It is not mandatory to implement the forced feature.
virtual void Shutdown(bool forced = false);
// Requests the backend to cancel the current render. Returns vfeNotRunning
// if there is no current render, vfeAlreadyStopping if a stop has already
// been requested, or vfeNoError otherwise. Also sets m_LastError in all
// cases. Note that this request is handled by the worker thread, like for
// vfeSession::Pause(), but unlike that request this one is handled
// asynchronously. This means you need to be prepared to handle the situation
// that even though you've called CancelRender(), the session hasn't caught
// up with the processing of the request yet.
virtual int CancelRender(void);
// Start a render. Will set m_LastError and return vfeRenderOptionsNotSet
// if you didn't call vfeSession::SetOptions() first. Otherwise will attempt
// to start the render; if this fails vfeFailedToSendRenderStart is returned.
// If the start attempt succeeds (note this is distinct from the start itself
// actually succeeding - all that the lack of a vfeFailedToSendRenderStart
// error means is that the start request was successfully sent to the backend)
// then a stRenderStartup notification is sent and the state is changed to
// kStarting.
//
// If the start attempt fails (signified by the receipt of a std::exception),
// the exception code will, in the case of a pov_base::Exception, be extracted
// and stored in m_LastError and returned; otherwise (not pov_base::Exception),
// m_LastError is set to -1. In either case, a failed status is set (so that
// vfeSession::Failed() will return true), and, if a fatal error message has
// not already been queued, the text of the exception will be added to both
// the status and error message queues.
virtual int StartRender(void);
// Sets the options to be used on the next render. Accepts a vfeRenderOptions
// instance as its only parameter, and returns any one of a number of possible
// error codes (and sets m_LastError), as documented below:
//
// vfeFailedToInitObject - this is an internal error
// vfeFailedToSetMaxThreads - self-explanatory
// vfeFailedToParseINI - an INI file specified could not be parsed
// vfeFailedToSetSource - the source file specified could not be set
// vfeFailedToParseCommand - a command-line option was invalid
// vfeNoInputFile - no input file specified either directly or via INI
// vfeRenderBlockSizeTooSmall - self-explanatory
// vfeFailedToWriteINI - a request to write the render options to an INI file failed
// vfeUnsupportedOptionCombination - at least two of the supplied options don't combine
//
// If vfeRenderOptions explicitly specifies a source file, it will override
// any set via a parsed INI file. Furthermore, any source file set via a
// command-line option overrides both of the above.
//
// Note that it is your responsibility to add any default INI files that should
// be processed to the INI file list; neither SetOptions() nor any other part
// of the VFE or POV-Ray code will do that for you. This includes non-platform
// specific files such as a potential povray.ini in the CWD.
virtual int SetOptions (vfeRenderOptions& opts);
// Clears any options set by vfeSession::SetOptions().
virtual void ClearOptions(void) { m_RenderOptions.Clear(); m_OptionsSet = false; }
// Returns true if the named option (e.g. "Output_To_File") is present in the
// render options. Will throw an exception if the options have not been set, or
// if the option name is invalid.
virtual bool OptionPresent(const char *OptionName);
// Will return the value of the named option, or the default value if it is not
// set. Will throw an exception for the same reasons as the OptionPresent() method.
// NOTE: this method won't always return what you expect; for example, if the user
// does not explicitly set the output file name, it won't be in the options, and
// thus won't be returned. That is to say, don't expect these methods to return
// the default values applied by the renderer in the absense of a specific value.
// This also applies to partial values, e.g. if the user sets "Output_File_Name=foo",
// we would return "foo", rather than for example "foo.png".
bool GetBoolOption(const char *OptionName, bool DefaultVal);
int GetIntOption(const char *OptionName, int DefaultVal);
float GetFloatOption(const char *OptionName, float DefaultVal);
std::string GetStringOption(const char *OptionName, const char *DefaultVal);
UCS2String GetUCS2StringOption(const char *OptionName, const UCS2String& DefaultVal);
// Helper method intended to tell VFE if it is running in a console-based
// client. If called with its boolean parameter set to true, the console
// word-wrap width will be set to 80, and an internal flag is set. Both
// this flag and the default wrap width are initially set to assume that
// a console build is in use, so a client platform only needs to call this
// if they are UI-based. If the value passed is false, the wrap width is
// set to 999, and furthermore any future warning or error messages received
// by the worker thread will additionally be added to the status message
// queue, along with the filename, line, and column where they occurred
// (assuming this was provided). UI-based clients can then, when they
// retrieve the status message, use its content to auto-display the error
// location in the source file if they so choose.
virtual void OptimizeForConsoleOutput(bool On) { m_OptimizeForConsoleOutput = On; m_ConsoleWidth = On ? 80 : 999; }
// Returns the raw POV-Ray internal state (e.g. kRendering etc)
virtual State GetBackendState() const { return m_BackendState; }
// Translates a state as returned from vfeSession::GetBackendState() into a string.
virtual const char *GetBackendStateName(void) const ;
// Return the input filename. This is not valid until vfeSession::SetOptions()
// has been called successfully.
virtual UCS2String GetInputFilename(void) const { return m_InputFilename; }
// Return the output filename. You should not call this until you have received
// a stOutputFilenameKnown status event. While it may be tempting to assume
// that the output filename is known as soon as the options are set, this is
// not necessarily the case - consider animations for example. Note it is
// also possible that you will never receive an stOutputFilenameKnown event
// since it is of course possible that output to file is turned off.
virtual UCS2String GetOutputFilename(void) const { return m_OutputFilename; }
// This method returns true if the current options specify that an output
// image should be written. It is only valid if vfeSession::SetOptions()
// has been called successfully.
virtual bool OutputToFileSet(void) const { return m_OutputToFileSet; }
// This method returns true if the current platform supports writing image
// output to STDOUT. Platforms that do not support this should override it.
virtual bool ImageOutputToStdoutSupported(void) const { return true; }
// This method returns the currently-set render width, in pixels.
// It is only valid if vfeSession::SetOptions() has been called successfully.
virtual int GetRenderWidth(void) const { return m_RenderWidth; }
// This method returns the currently-set render height, in pixels.
// It is only valid if vfeSession::SetOptions() has been called successfully.
virtual int GetRenderHeight(void) const { return m_RenderHeight; }
// This method returns a reference to the vfeRenderOptions instance stored
// within vfe. After vfeSession::SetOptions() is called successfully, the
// supplied options are copied into the internal instance.
virtual vfeRenderOptions& GetOptions() { return m_RenderOptions; }
// Fetches one message from either the generic, status, or console message
// queues, whichever has the earliest timestamp. Returns true if a message
// is fetched, otherwise false (meaning all the queues are empty). It expects
// two parameters - a reference to a MessageType, in which the type of the
// returned message is stored, and a std::string, which will be set to the
// actual message text. Note that linefeeds are not appended.
//
// This method is primarily useful for console-style displays as it discards
// any additional meta-information the message may have had, such as the
// line number of an error. (Note that this does not mean the line number
// cannot be in the message string; it may very well be).
virtual bool GetNextCombinedMessage (MessageType &Type, string& Message);
// Gets the next non-status message (meaning generic or console messages)
// from the aforementioned queues; whichever is the earliest. Returns false
// if there is no message to fetch, otherwise will set the message type,
// filename, line, and column parameters supplied. If the message retrieved
// did not contain this information, the relevent entry is either set to 0
// (line and column) or the empty string (filename). The filename parameter
// is a UCS2String.
virtual bool GetNextNonStatusMessage (MessageType &Type, string& Message, UCS2String& File, int& Line, int& Col);
// Gets the next non-status message (meaning generic or console messages)
// from the aforementioned queues; whichever is the earliest. Returns false
// if there is no message to fetch, otherwise will set the message type,
// filename, line, and column parameters supplied. If the message retrieved
// did not contain this information, the relevent entry is either set to 0
// (line and column) or the empty string (filename). The filename parameter
// is a std::string.
virtual bool GetNextNonStatusMessage (MessageType &Type, string& Message, string& File, int& Line, int& Col);
// Gets the next non-status message (meaning generic or console messages)
// from the aforementioned queues; whichever is the earliest. Returns false
// if there is no message to fetch, otherwise will set the message type
// and text content parameters supplied. Any additional meta-information
// that may have been contained in the message is discarded.
virtual bool GetNextNonStatusMessage (MessageType &Type, string& Message);
// Returns false if there are no messages in the status message
// queue, otherwise removes the oldest status message from the
// queue and copies it into the StatusMessage reference supplied
// as a parameter, then returns true.
virtual bool GetNextStatusMessage (StatusMessage& Message);
// Returns false if there are no messages in the generic message
// queue, otherwise removes the oldest message from the queue and
// copies it into the GenericMessage reference supplied as a
// parameter, then returns true.
virtual bool GetNextGenericMessage (GenericMessage& Message);
// Returns false if there are no messages in the console message
// queue, otherwise removes the oldest message from the queue and
// copies it into the MessageBase reference supplied as a parameter,
// then returns true.
virtual bool GetNextConsoleMessage (MessageBase& Message);
// Returns a std::string potentially useful for displaying in the status
// line (or other similar UI element) of a UI-based client implementation.
// The VFE internal code takes care of setting this to what it considers
// reasonable values and issuing either a stStatusMessage or stAnimationStatus
// event notification, as appropriate. Upon receiving either of the above
// events therefore you may like to simply call this method and place the
// returned value wherever suitable, overwriting the previous value.2
virtual string GetStatusLineMessage() { return m_StatusLineMessage; }
// Sets the maximum number of status messages that will be stored in the
// status queue. If this limit is reached, the oldest message will be
// discarded each time a new message is added. The default value is -1,
// which means that there is no limit.
virtual void SetMaxStatusMessages (int Max) { m_MaxStatusMessages = Max; }
// Sets the maximum number of generic messages that will be stored in the
// status queue. If this limit is reached, the oldest message will be
// discarded each time a new message is added. The default value is -1,
// which means that there is no limit.
virtual void SetMaxGenericMessages (int Max) { m_MaxGenericMessages = Max; }
// Sets the maximum number of console messages that will be stored in the
// status queue. If this limit is reached, the oldest message will be
// discarded each time a new message is added. The default value is -1,
// which means that there is no limit.
virtual void SetMaxConsoleMessages (int Max) { m_MaxConsoleMessages = Max; }
// Returns a string giving a short english description of the error code
// supplied as the only parameter. If no parameter is supplied, the default
// value (-1) instructs the method to instead use the value of m_LastError.
virtual const char *GetErrorString(int code = -1) const ;
// Returns true if opening the given file in the specified mode is to
// be permitted. It is allowed to ask the user, so this method could
// take some time to return (especially if user is not at workstation).
// The default implementation simply returns true. Platforms should
// override this method and do something more useful (see the Windows
// implementation in vfe/win/vfeplatform.cpp).
virtual bool TestAccessAllowed(const Path& file, bool isWrite) const { return true; }
// Allows you to manually set the console wrap width.
// The supplied value is clipped to the range 80-999.
virtual void SetConsoleWidth(int width) { m_ConsoleWidth = max(min(999,width),80); }
// Return the current console wrap width.
virtual int GetConsoleWidth(void) { return m_ConsoleWidth; }
// Clear all IO Restriction-related paths previously set.
virtual void ClearPaths() { m_ReadPaths.clear(); m_WritePaths.clear(); m_ExcludedPaths.clear(); }
// Adds the supplied path to the list of allowed read paths, along with
// the recursive flag (meaning paths under that path are also allowed).
// The supplied path is a pov_base::Path instance.
virtual void AddReadPath(const Path& path, bool recursive = true) { m_ReadPaths.push_back(IOPath(path, recursive)); }
// Adds the supplied path to the list of allowed read paths, along with
// the recursive flag (meaning paths under that path are also allowed).
// The supplied path is a UCS2String.
virtual void AddReadPath(const UCS2String& path, bool recursive = true) { m_ReadPaths.push_back(IOPath(path, recursive)); }
// Adds the supplied path to the list of allowed read paths, along with
// the recursive flag (meaning paths under that path are also allowed).
// The supplied path is a std::string.
virtual void AddReadPath(const string& path, bool recursive = true) { m_ReadPaths.push_back(IOPath(path, recursive)); }
// Adds the supplied path to the list of allowed read paths.
// The supplied path is a pre-constructed IOPath instance.
virtual void AddReadPath(const IOPath& path) { m_ReadPaths.push_back(path); }
// Adds the supplied path to the list of allowed write paths, along with
// the recursive flag (meaning paths under that path are also allowed).
// The supplied path is a pov_base::Path instance.
virtual void AddWritePath(const Path& path, bool recursive = true) { m_WritePaths.push_back(IOPath(path, recursive)); }
// Adds the supplied path to the list of allowed write paths, along with
// the recursive flag (meaning paths under that path are also allowed).
// The supplied path is a UCS2String.
virtual void AddWritePath(const UCS2String& path, bool recursive = true) { m_WritePaths.push_back(IOPath(path, recursive)); }
// Adds the supplied path to the list of allowed write paths, along with
// the recursive flag (meaning paths under that path are also allowed).
// The supplied path is a std::string.
virtual void AddWritePath(const string& path, bool recursive = true) { m_WritePaths.push_back(IOPath(path, recursive)); }
// Adds the supplied path to the list of allowed write paths.
// The supplied path is a pre-constructed IOPath instance.
virtual void AddWritePath(const IOPath& path) { m_WritePaths.push_back(path); }
// Adds the supplied path to the list of excluded paths, along with the
// recursion flag. A path in the exclusion list is never allowed to be
// written to, even if it would be otherwise permitted by a write path.
// Unlike read and write paths, which may be specified by users, the
// intent of excluded paths is to allow client implementations to hard-
// code certain paths that may never be written to, such as the location
// of the platform's master configuration files (that presumably contain
// contain the user-specified read and write path settings). The supplied
// path is a pov_base::Path instance.
virtual void AddExcludedPath(const Path& path, bool recursive = true) { m_ExcludedPaths.push_back(IOPath(path, recursive)); }
// Adds the supplied path to the list of excluded paths, along with the
// recursion flag. The supplied path is a UCS2String.
virtual void AddExcludedPath(const UCS2String& path, bool recursive = true) { m_ExcludedPaths.push_back(IOPath(path, recursive)); }
// Adds the supplied path to the list of excluded paths, along with the
// recursion flag. The supplied path is a std::string.
virtual void AddExcludedPath(const string& path, bool recursive = true) { m_ExcludedPaths.push_back(IOPath(path, recursive)); }
// Adds the supplied path to the list of excluded paths, along with the
// recursion flag. The supplied path is a pre-constructed IOPath instance.
virtual void AddExcludedPath(const IOPath& path) { m_ExcludedPaths.push_back(path); }
// Returns a const reference to the list of permitted read paths.
virtual const IOPathVector& GetReadPaths() const { return m_ReadPaths; }
// Returns a copy of the list of permitted read paths.
virtual IOPathVector GetReadPaths() { return m_ReadPaths; }
// Returns a const reference to the list of permitted write paths.
virtual const IOPathVector& GetWritePaths() const { return m_WritePaths; }
// Returns a copy of the list of permitted write paths.
virtual IOPathVector GetWritePaths() { return m_WritePaths; }
// Returns a const reference to the list of excluded paths.
virtual const IOPathVector& GetExcludedPaths() const { return m_ExcludedPaths; }
// This static method is used to return the vfeSession associated with
// the calling thread (if any). In a full multi-session-enabled
// implementation of vfe, it would look up the session from a list of
// active sessions keyed with the value returned from GetThreadID().
// Currently as only one session is supported (this is enforced in the
// vfeSession::Initialize() method) it simply returns the value of a
// global variable.
static vfeSession *GetSessionFromThreadID() ;
// These methods just return whether or not the named option is in effect.
// They are only valid once vfeParserMessageHandler::Options has been called.
virtual bool GetUsingAlpha() { return m_UsingAlpha; }
virtual bool GetClocklessAnimation() { return m_ClocklessAnimation; }
virtual bool GetRealTimeRaytracing() { return m_RealTimeRaytracing; }
// return elapsed time in the render as milliseconds. only valid once the
// state changs to rendering.
virtual POV_LONG GetElapsedTime() { return GetTimestamp() - m_StartTime; }
virtual void AppendErrorMessage (const string& Msg);
virtual void AppendWarningMessage (const string& Msg);
virtual void AppendStatusMessage (const string& Msg, int RecommendedPause = 0);
virtual void AppendStatusMessage (const boost::format& fmt, int RecommendedPause = 0);
virtual void AppendWarningAndStatusMessage (const string& Msg, int RecommendedPause = 0) { AppendWarningMessage(Msg); AppendStatusMessage(Msg, RecommendedPause); }
virtual void AppendErrorAndStatusMessage (const string& Msg, int RecommendedPause = 0) { AppendErrorMessage(Msg); AppendStatusMessage(Msg, RecommendedPause); }
// returns true if a render cancel was requested at some point since the render started.
virtual bool GetCancelRequested() { return m_RenderCancelRequested | m_RenderCancelled ; }
// returns true if the main POV-Ray backend has shut down
virtual bool BackendFailed() { return m_BackendThreadExited; }
protected:
// All of the following are internal to vfe.
virtual void SetFailed();
virtual void SetSucceeded (bool ok);
virtual void AdviseOutputFilename(const UCS2String& Filename);
virtual void AdviseFrameCompleted();
virtual void SetRenderingAnimation();
virtual void SetPercentComplete(int Percent) { m_PercentComplete = Percent; }
virtual void SetPixelsRendered(int Rendered, int Total) { m_PixelsRendered = Rendered; m_TotalPixels = Total; }
virtual void AppendStreamMessage (MessageType type, const char *message, bool chompLF = false);
virtual void AppendStreamMessage (MessageType type, const boost::format& fmt, bool chompLF = false);
virtual void AppendErrorMessage (const string& Msg, const UCS2String& File, int Line = 0, int Col = 0);
virtual void AppendWarningMessage (const string& Msg, const UCS2String& File, int Line = 0, int Col = 0);
virtual void AppendAnimationStatus (int Frame, int Total, const UCS2String& Filename);
virtual void SetUsingAlpha() { m_UsingAlpha = true ; }
virtual void SetClocklessAnimation() { m_ClocklessAnimation = true ; }
virtual void SetRealTimeRaytracing() { m_RealTimeRaytracing = true ; }
virtual void NotifyEvent(vfeStatusFlags Status);
virtual void BackendThreadNotify();
virtual void WorkerThread();
virtual void WorkerThreadStartup() {}
virtual void WorkerThreadShutdown() {}
virtual bool ProcessFrontend (void);
virtual bool ProcessCancelRender(void);
virtual bool StopRender(const string& reason);
// This method allows your platform code to perform platform-specific actions
// when a render stops (whether it succeeds or fails). A good example would
// be to shrink the heap. Be aware that it is called in the context of the
// worker thread, and that therefore on windowing systems where thread context
// is relevent to making certain UI calls, it may not be possible to perform
// certain UI actions here. For most platforms the default implementation
// should be sufficient.
virtual void RenderStopped(void);
// Platforms that support the ability to return excess heap memory to
// the operating system should implement this method.
virtual void ShrinkHeap() {}
// Hook this if you want to directly catch state change events (but if
// you do, ensure you call back to the default implementation as well).
virtual void StateChanged(pov_frontend::State NewState);
/////////////////////////////////////////////////////////////////////////
// This method will get called when a render completes and the image writing
// code is unable to write the requested output file for some reason (e.g.
// disk full, existing output file is read-only, or whatever). The return
// value can determine any one of several possible actions the code will take.
// It's up to you what you do here, but a typical example would be to display
// an error dialog showing the reason (which will be a short string) and the old
// path, and allow the user to browse for a new path (you may want to auto-
// suggest one). It is allowable to perform tests yourself on the path to
// obtain some OS-specific information as to why it failed in order to better
// determine what to suggest as the new path (e.g. the the output path is
// not writable due to insufficient privileges, you may want to default the
// new path to the user's home directory).
//
// Any new path that is to be returned should be placed in NewPath. The parameter
// CallCount will initially be 0, and represents the number of times the
// method has been called for a given rendering; this allows you for example
// to auto-default on the first call and prompt the user on subsequent ones.
// (Note that if you do this and the auto-default succeeds, it's up to you to
// notify the user that the output file is not what they originally asked for).
//
// You may want to place a timeout on this dialog if the session is running
// an animation and return in the case of a timeout a default value.
//
// The return values can be any of the following:
//
// 0 : don't try again, leave the render without an output file but preserve
// the state file (so a render with +c will reload the image data).
// 1 : reserved for later support
// 2 : don't try again and delete the state file (rendered data can't be
// recovered).
// 3 : try again with the same file (NewPath is ignored).
// 4 : try again with the new path returned in NewPath.
//
// Note that if you choose to specify any of the "don't try again" options,
// and the session happens to be an animation, and it's likely the same
// error will occur again (e.g. invalid output path or something), then
// you may want to call the render cancel API so the user isn't bombarded
// with an error message for each frame of the render.
//
// NB this method is pure virtual.
//
// NOTE: The code to call this method isn't implemented in vfe yet.
virtual int RequestNewOutputPath(int CallCount, const string& Reason, const UCS2String& OldPath, UCS2String& NewPath) = 0;
// Create an instance of the frontend ShelloutProcessing class. this handles creating and
// managing render shellout commands, and typically will need platform-specific implementation.
virtual ShelloutProcessing *CreateShelloutProcessing(POVMS_Object& opts, const string& scene, uint width, uint height) { return new ShelloutProcessing(opts, scene, width, height); }
struct vfeSessionWorker
{
vfeSessionWorker(vfeSession& Parent) : m_Parent(Parent) {}
void operator()() { m_Parent.WorkerThread(); }
vfeSession& m_Parent;
};
int m_Id;
int m_RenderWidth;
int m_RenderHeight;
int m_RenderErrorCode;
int m_InitializeErrorCode;
int m_LastError;
int m_ConsoleWidth;
int m_PercentComplete;
int m_PixelsRendered;
int m_TotalPixels;
int m_CurrentFrame;
int m_TotalFrames;
bool m_Failed;
bool m_Succeeded;
bool m_HadErrorMessage;
bool m_UsingAlpha;
bool m_RenderingAnimation;
bool m_RealTimeRaytracing;
bool m_ClocklessAnimation;
bool m_HadCriticalError;
bool m_RenderCancelled;
bool m_RenderCancelRequested;
bool m_DontWriteImage;
bool m_OutputToFileSet;
bool m_OptionsSet;
bool m_OptimizeForConsoleOutput;
bool m_PauseWhenDone;
POV_LONG m_StartTime;
unsigned int m_MessageCount;
vfeStatusFlags m_EventMask;
vfeStatusFlags m_StatusFlags;
vfeRenderOptions m_RenderOptions;
static bool m_Initialized;
static vfeSession *m_CurrentSessionTemporaryHack;
shared_ptr<Console> m_Console;
virtual vfeDisplay *DefaultDisplayCreator (unsigned int width, unsigned int height, GammaCurvePtr gamma, vfeSession *session, bool visible);
DisplayCreator m_DisplayCreator;
int m_MaxStatusMessages;
int m_MaxGenericMessages;
int m_MaxConsoleMessages;
GenericQueue m_MessageQueue;
StatusQueue m_StatusQueue;
ConsoleQueue m_ConsoleQueue;
string m_StatusLineMessage;
UCS2String m_OutputFilename;
UCS2String m_InputFilename;
IOPathVector m_ReadPaths;
IOPathVector m_WritePaths;
IOPathVector m_ExcludedPaths;
VirtualFrontEnd *m_Frontend;
State m_BackendState;
boost::mutex m_MessageMutex;
boost::mutex m_SessionMutex;
boost::condition m_SessionEvent;
boost::mutex m_InitializeMutex;
boost::condition m_InitializeEvent;
boost::condition m_ShutdownEvent;
boost::thread *m_WorkerThread;
boost::thread *m_BackendThread;
volatile bool m_WorkerThreadExited;
volatile bool m_BackendThreadExited;
volatile bool m_WorkerThreadShutdownRequest;
boost::mutex m_RequestMutex;
boost::condition m_RequestEvent;
volatile int m_RequestFlag;
volatile int m_RequestResult;
} ;
}
#endif // __VFESESSION_H__
Reference in a new issue View git blame Copy permalink