1 /* 2 * Copyright (C) 2016-2018 Team Kodi 3 * This file is part of Kodi - https://kodi.tv 4 * 5 * SPDX-License-Identifier: GPL-2.0-or-later 6 * See LICENSES/README.md for more information. 7 */ 8 9 #pragma once 10 11 #include <stddef.h> 12 #include <stdint.h> 13 14 namespace KODI 15 { 16 namespace RETRO 17 { 18 /*! 19 * \brief Stream of serialized states from game clients 20 * 21 * A memory stream is composed of "frames" of memory representing serialized 22 * states of the game client. For each video frame run by the game loop, the 23 * game client's state is serialized into a buffer provided by this interface. 24 * 25 * Implementation of three types of memory streams are provided: 26 * 27 * - Basic memory stream: has only a current frame, and supports neither 28 * rewind nor forward seeking. 29 * 30 * \sa CBasicMemoryStream 31 * 32 * - Linear memory stream: can grow in one direction. It is possible to 33 * rewind, but not fast-forward. 34 * 35 * \sa CLinearMemoryStream 36 * 37 * - Nonlinear memory stream: can have frames both ahead of and behind 38 * the current frame. If a stream is rewound, it is possible to 39 * recover these frames by seeking forward again. 40 * 41 * \sa CNonlinearMemoryStream (TODO) 42 */ 43 class IMemoryStream 44 { 45 public: 46 virtual ~IMemoryStream() = default; 47 48 /*! 49 * \brief Initialize memory stream 50 * 51 * \param frameSize The size of the serialized memory state 52 * \param maxFrameCount The maximum number of frames this stream can hold 53 */ 54 virtual void Init(size_t frameSize, uint64_t maxFrameCount) = 0; 55 56 /*! 57 * \brief Free any resources used by this stream 58 */ 59 virtual void Reset() = 0; 60 61 /*! 62 * \brief Return the frame size passed to Init() 63 */ 64 virtual size_t FrameSize() const = 0; 65 66 /*! 67 * \brief Return the current max frame count 68 */ 69 virtual uint64_t MaxFrameCount() const = 0; 70 71 /*! 72 * \brief Update the max frame count 73 * 74 * Old frames may be deleted if the max frame count is reduced. 75 */ 76 virtual void SetMaxFrameCount(uint64_t maxFrameCount) = 0; 77 78 /*! 79 * \ brief Get a pointer to which FrameSize() bytes can be written 80 * 81 * The buffer exposed by this function is passed to the game client, which 82 * fills it with a serialization of its current state. 83 */ 84 virtual uint8_t* BeginFrame() = 0; 85 86 /*! 87 * \brief Indicate that a frame of size FrameSize() has been written to the 88 * location returned from BeginFrame() 89 */ 90 virtual void SubmitFrame() = 0; 91 92 /*! 93 * \brief Get a pointer to the current frame 94 * 95 * This function must have no side effects. The pointer is valid until the 96 * stream is modified. 97 * 98 * \return A buffer of size FrameSize(), or nullptr if the stream is empty 99 */ 100 virtual const uint8_t* CurrentFrame() const = 0; 101 102 /*! 103 * \brief Return the number of frames ahead of the current frame 104 * 105 * If the stream supports forward seeking, frames that are passed over 106 * during a "rewind" operation can be recovered again. 107 */ 108 virtual uint64_t FutureFramesAvailable() const = 0; 109 110 /*! 111 * \brief Seek ahead the specified number of frames 112 * 113 * \return The number of frames advanced 114 */ 115 virtual uint64_t AdvanceFrames(uint64_t frameCount) = 0; 116 117 /*! 118 * \brief Return the number of frames behind the current frame 119 */ 120 virtual uint64_t PastFramesAvailable() const = 0; 121 122 /*! 123 * \brief Seek backwards the specified number of frames 124 * 125 * \return The number of frames rewound 126 */ 127 virtual uint64_t RewindFrames(uint64_t frameCount) = 0; 128 129 /*! 130 * \brief Get the total number of frames played until the current frame 131 * 132 * \return The history of the current frame, or 0 for unknown 133 */ 134 virtual uint64_t GetFrameCounter() const = 0; 135 136 /*! 137 * \brief Set the total number of frames played until the current frame 138 * 139 * \param frameCount The history of the current frame 140 */ 141 virtual void SetFrameCounter(uint64_t frameCount) = 0; 142 }; 143 } // namespace RETRO 144 } // namespace KODI 145