summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
Diffstat
-rw-r--r--indra/llplugin/llpluginmessage.cpp160
-rw-r--r--indra/llplugin/llpluginmessage.h10
-rw-r--r--indra/media_plugins/base/media_plugin_base.cpp56
-rw-r--r--indra/media_plugins/base/media_plugin_base.h44
4 files changed, 256 insertions, 14 deletions
diff --git a/indra/llplugin/llpluginmessage.cpp b/indra/llplugin/llpluginmessage.cpp
index 34e02c356e..d06f3cefa0 100644
--- a/indra/llplugin/llpluginmessage.cpp
+++ b/indra/llplugin/llpluginmessage.cpp
@@ -37,31 +37,57 @@
#include "llsdserialize.h"
#include "u64.h"
+/**
+ * Constructor.
+ */
LLPluginMessage::LLPluginMessage()
{
}
+/**
+ * Constructor.
+ *
+ * @param[in] p Existing message
+ */
LLPluginMessage::LLPluginMessage(const LLPluginMessage &p)
{
mMessage = p.mMessage;
}
+/**
+ * Constructor.
+ *
+ * @param[in] message_class Message class
+ * @param[in] message_name Message name
+ */
LLPluginMessage::LLPluginMessage(const std::string &message_class, const std::string &message_name)
{
setMessage(message_class, message_name);
}
+/**
+ * Destructor.
+ */
LLPluginMessage::~LLPluginMessage()
{
}
+/**
+ * Reset all internal state.
+ */
void LLPluginMessage::clear()
{
mMessage = LLSD::emptyMap();
mMessage["params"] = LLSD::emptyMap();
}
+/**
+ * Sets the message class and name. Also has the side-effect of clearing any key-value pairs in the message.
+ *
+ * @param[in] message_class Message class
+ * @param[in] message_name Message name
+ */
void LLPluginMessage::setMessage(const std::string &message_class, const std::string &message_name)
{
clear();
@@ -69,21 +95,45 @@ void LLPluginMessage::setMessage(const std::string &message_class, const std::st
mMessage["name"] = message_name;
}
+/**
+ * Sets a key/value pair in the message, where the value is a string.
+ *
+ * @param[in] key Key
+ * @param[in] value String value
+ */
void LLPluginMessage::setValue(const std::string &key, const std::string &value)
{
mMessage["params"][key] = value;
}
+/**
+ * Sets a key/value pair in the message, where the value is LLSD.
+ *
+ * @param[in] key Key
+ * @param[in] value LLSD value
+ */
void LLPluginMessage::setValueLLSD(const std::string &key, const LLSD &value)
{
mMessage["params"][key] = value;
}
+/**
+ * Sets a key/value pair in the message, where the value is signed 32-bit.
+ *
+ * @param[in] key Key
+ * @param[in] value 32-bit signed value
+ */
void LLPluginMessage::setValueS32(const std::string &key, S32 value)
{
mMessage["params"][key] = value;
}
+/**
+ * Sets a key/value pair in the message, where the value is unsigned 32-bit. The value is stored as a string beginning with "0x".
+ *
+ * @param[in] key Key
+ * @param[in] value 32-bit unsigned value
+ */
void LLPluginMessage::setValueU32(const std::string &key, U32 value)
{
std::stringstream temp;
@@ -91,16 +141,34 @@ void LLPluginMessage::setValueU32(const std::string &key, U32 value)
setValue(key, temp.str());
}
+/**
+ * Sets a key/value pair in the message, where the value is a bool.
+ *
+ * @param[in] key Key
+ * @param[in] value Boolean value
+ */
void LLPluginMessage::setValueBoolean(const std::string &key, bool value)
{
mMessage["params"][key] = value;
}
+/**
+ * Sets a key/value pair in the message, where the value is a double.
+ *
+ * @param[in] key Key
+ * @param[in] value Boolean value
+ */
void LLPluginMessage::setValueReal(const std::string &key, F64 value)
{
mMessage["params"][key] = value;
}
+/**
+ * Sets a key/value pair in the message, where the value is a pointer. The pointer is stored as a string.
+ *
+ * @param[in] key Key
+ * @param[in] value Pointer value
+ */
void LLPluginMessage::setValuePointer(const std::string &key, void* value)
{
std::stringstream temp;
@@ -109,16 +177,33 @@ void LLPluginMessage::setValuePointer(const std::string &key, void* value)
setValue(key, temp.str());
}
+/**
+ * Gets the message class.
+ *
+ * @return Message class
+ */
std::string LLPluginMessage::getClass(void) const
{
return mMessage["class"];
}
+/**
+ * Gets the message name.
+ *
+ * @return Message name
+ */
std::string LLPluginMessage::getName(void) const
{
return mMessage["name"];
}
+/**
+ * Returns true if the specified key exists in this message (useful for optional parameters).
+ *
+ * @param[in] key Key
+ *
+ * @return True if key exists, false otherwise.
+ */
bool LLPluginMessage::hasValue(const std::string &key) const
{
bool result = false;
@@ -131,6 +216,13 @@ bool LLPluginMessage::hasValue(const std::string &key) const
return result;
}
+/**
+ * Gets the value of a key as a string. If the key does not exist, an empty string will be returned.
+ *
+ * @param[in] key Key
+ *
+ * @return String value of key if key exists, empty string if key does not exist.
+ */
std::string LLPluginMessage::getValue(const std::string &key) const
{
std::string result;
@@ -143,6 +235,13 @@ std::string LLPluginMessage::getValue(const std::string &key) const
return result;
}
+/**
+ * Gets the value of a key as LLSD. If the key does not exist, a null LLSD will be returned.
+ *
+ * @param[in] key Key
+ *
+ * @return LLSD value of key if key exists, null LLSD if key does not exist.
+ */
LLSD LLPluginMessage::getValueLLSD(const std::string &key) const
{
LLSD result;
@@ -155,6 +254,13 @@ LLSD LLPluginMessage::getValueLLSD(const std::string &key) const
return result;
}
+/**
+ * Gets the value of a key as signed 32-bit int. If the key does not exist, 0 will be returned.
+ *
+ * @param[in] key Key
+ *
+ * @return Signed 32-bit int value of key if key exists, 0 if key does not exist.
+ */
S32 LLPluginMessage::getValueS32(const std::string &key) const
{
S32 result = 0;
@@ -167,6 +273,13 @@ S32 LLPluginMessage::getValueS32(const std::string &key) const
return result;
}
+/**
+ * Gets the value of a key as unsigned 32-bit int. If the key does not exist, 0 will be returned.
+ *
+ * @param[in] key Key
+ *
+ * @return Unsigned 32-bit int value of key if key exists, 0 if key does not exist.
+ */
U32 LLPluginMessage::getValueU32(const std::string &key) const
{
U32 result = 0;
@@ -181,6 +294,13 @@ U32 LLPluginMessage::getValueU32(const std::string &key) const
return result;
}
+/**
+ * Gets the value of a key as a bool. If the key does not exist, false will be returned.
+ *
+ * @param[in] key Key
+ *
+ * @return Boolean value of key if it exists, false otherwise.
+ */
bool LLPluginMessage::getValueBoolean(const std::string &key) const
{
bool result = false;
@@ -193,6 +313,13 @@ bool LLPluginMessage::getValueBoolean(const std::string &key) const
return result;
}
+/**
+ * Gets the value of a key as a double. If the key does not exist, 0 will be returned.
+ *
+ * @param[in] key Key
+ *
+ * @return Value as a double if key exists, 0 otherwise.
+ */
F64 LLPluginMessage::getValueReal(const std::string &key) const
{
F64 result = 0.0f;
@@ -205,6 +332,13 @@ F64 LLPluginMessage::getValueReal(const std::string &key) const
return result;
}
+/**
+ * Gets the value of a key as a pointer. If the key does not exist, NULL will be returned.
+ *
+ * @param[in] key Key
+ *
+ * @return Pointer value if key exists, NULL otherwise.
+ */
void* LLPluginMessage::getValuePointer(const std::string &key) const
{
void* result = NULL;
@@ -219,6 +353,11 @@ void* LLPluginMessage::getValuePointer(const std::string &key) const
return result;
}
+/**
+ * Flatten the message into a string.
+ *
+ * @return Message as a string.
+ */
std::string LLPluginMessage::generate(void) const
{
std::ostringstream result;
@@ -230,7 +369,11 @@ std::string LLPluginMessage::generate(void) const
return result.str();
}
-
+/**
+ * Parse an incoming message into component parts. Clears all existing state before starting the parse.
+ *
+ * @return Returns -1 on failure, otherwise returns the number of key/value pairs in the incoming message.
+ */
int LLPluginMessage::parse(const std::string &message)
{
// clear any previous state
@@ -255,16 +398,31 @@ LLPluginMessageDispatcher::~LLPluginMessageDispatcher()
}
+/**
+ * Add a message listener. TODO:DOC need more info on what uses this. when are multiple listeners needed?
+ *
+ * @param[in] listener Message listener
+ */
void LLPluginMessageDispatcher::addPluginMessageListener(LLPluginMessageListener *listener)
{
mListeners.insert(listener);
}
+/**
+ * Remove a message listener.
+ *
+ * @param[in] listener Message listener
+ */
void LLPluginMessageDispatcher::removePluginMessageListener(LLPluginMessageListener *listener)
{
mListeners.erase(listener);
}
+/**
+ * Distribute a message to all message listeners.
+ *
+ * @param[in] message Message
+ */
void LLPluginMessageDispatcher::dispatchPluginMessage(const LLPluginMessage &message)
{
for (listener_set_t::iterator it = mListeners.begin();
diff --git a/indra/llplugin/llpluginmessage.h b/indra/llplugin/llpluginmessage.h
index 99f8d1194f..e00022a245 100644
--- a/indra/llplugin/llpluginmessage.h
+++ b/indra/llplugin/llpluginmessage.h
@@ -104,6 +104,9 @@ private:
};
+/**
+ * @brief Listens for plugin messages.
+ */
class LLPluginMessageListener
{
public:
@@ -112,6 +115,11 @@ public:
};
+/**
+ * @brief Dispatcher for plugin messages.
+ *
+ * Manages the set of plugin message listeners and distributes messages to plugin message listeners.
+ */
class LLPluginMessageDispatcher
{
public:
@@ -122,7 +130,9 @@ public:
protected:
void dispatchPluginMessage(const LLPluginMessage &message);
+ /** A set of message listeners. */
typedef std::set<LLPluginMessageListener*> listener_set_t;
+ /** The set of message listeners. */
listener_set_t mListeners;
};
diff --git a/indra/media_plugins/base/media_plugin_base.cpp b/indra/media_plugins/base/media_plugin_base.cpp
index 8c8fa24a65..658783e064 100644
--- a/indra/media_plugins/base/media_plugin_base.cpp
+++ b/indra/media_plugins/base/media_plugin_base.cpp
@@ -2,6 +2,8 @@
* @file media_plugin_base.cpp
* @brief Media plugin base class for LLMedia API plugin system
*
+ * All plugins should be a subclass of MediaPluginBase.
+ *
* @cond
* $LicenseInfo:firstyear=2008&license=viewergpl$
*
@@ -37,7 +39,10 @@
// TODO: Make sure that the only symbol exported from this library is LLPluginInitEntryPoint
////////////////////////////////////////////////////////////////////////////////
-//
+/// Media plugin constructor.
+///
+/// @param[in] host_send_func Function for sending messages from plugin to plugin loader shell
+/// @param[in] host_user_data Message data for messages from plugin to plugin loader shell
MediaPluginBase::MediaPluginBase(
LLPluginInstance::sendMessageFunction host_send_func,
@@ -55,6 +60,12 @@ MediaPluginBase::MediaPluginBase(
mStatus = STATUS_NONE;
}
+/**
+ * Converts current media status enum value into string (STATUS_LOADING into "loading", etc.)
+ *
+ * @return Media status string ("loading", "playing", "paused", etc)
+ *
+ */
std::string MediaPluginBase::statusString()
{
std::string result;
@@ -75,6 +86,12 @@ std::string MediaPluginBase::statusString()
return result;
}
+/**
+ * Set media status.
+ *
+ * @param[in] status Media status (STATUS_LOADING, STATUS_PLAYING, STATUS_PAUSED, etc)
+ *
+ */
void MediaPluginBase::setStatus(EStatus status)
{
if(mStatus != status)
@@ -85,6 +102,13 @@ void MediaPluginBase::setStatus(EStatus status)
}
+/**
+ * Receive message from plugin loader shell.
+ *
+ * @param[in] message_string Message string
+ * @param[in] user_data Message data
+ *
+ */
void MediaPluginBase::staticReceiveMessage(const char *message_string, void **user_data)
{
MediaPluginBase *self = (MediaPluginBase*)*user_data;
@@ -102,12 +126,27 @@ void MediaPluginBase::staticReceiveMessage(const char *message_string, void **us
}
}
+/**
+ * Send message to plugin loader shell.
+ *
+ * @param[in] message Message data being sent to plugin loader shell
+ *
+ */
void MediaPluginBase::sendMessage(const LLPluginMessage &message)
{
std::string output = message.generate();
mHostSendFunction(output.c_str(), &mHostUserData);
}
+/**
+ * Notifies plugin loader shell that part of display area needs to be redrawn.
+ *
+ * @param[in] left Left X coordinate of area to redraw (0,0 is at top left corner)
+ * @param[in] top Top Y coordinate of area to redraw (0,0 is at top left corner)
+ * @param[in] right Right X-coordinate of area to redraw (0,0 is at top left corner)
+ * @param[in] bottom Bottom Y-coordinate of area to redraw (0,0 is at top left corner)
+ *
+ */
void MediaPluginBase::setDirty(int left, int top, int right, int bottom)
{
LLPluginMessage message(LLPLUGIN_MESSAGE_CLASS_MEDIA, "updated");
@@ -120,6 +159,10 @@ void MediaPluginBase::setDirty(int left, int top, int right, int bottom)
sendMessage(message);
}
+/**
+ * Sends "media_status" message to plugin loader shell ("loading", "playing", "paused", etc.)
+ *
+ */
void MediaPluginBase::sendStatus()
{
LLPluginMessage message(LLPLUGIN_MESSAGE_CLASS_MEDIA, "media_status");
@@ -143,6 +186,17 @@ extern "C"
LLSYMEXPORT int LLPluginInitEntryPoint(LLPluginInstance::sendMessageFunction host_send_func, void *host_user_data, LLPluginInstance::sendMessageFunction *plugin_send_func, void **plugin_user_data);
}
+/**
+ * Plugin initialization and entry point. Establishes communication channel for messages between plugin and plugin loader shell. TODO:DOC - Please check!
+ *
+ * @param[in] host_send_func Function for sending messages from plugin to plugin loader shell
+ * @param[in] host_user_data Message data for messages from plugin to plugin loader shell
+ * @param[out] plugin_send_func Function for plugin to receive messages from plugin loader shell
+ * @param[out] plugin_user_data Pointer to plugin instance
+ *
+ * @return int, where 0=success
+ *
+ */
LLSYMEXPORT int
LLPluginInitEntryPoint(LLPluginInstance::sendMessageFunction host_send_func, void *host_user_data, LLPluginInstance::sendMessageFunction *plugin_send_func, void **plugin_user_data)
{
diff --git a/indra/media_plugins/base/media_plugin_base.h b/indra/media_plugins/base/media_plugin_base.h
index 4dd157a07c..ed4dc0cfa9 100644
--- a/indra/media_plugins/base/media_plugin_base.h
+++ b/indra/media_plugins/base/media_plugin_base.h
@@ -42,14 +42,17 @@ class MediaPluginBase
{
public:
MediaPluginBase(LLPluginInstance::sendMessageFunction host_send_func, void *host_user_data);
+ /** Media plugin destructor. */
virtual ~MediaPluginBase() {}
+ /** Handle received message from plugin loader shell. */
virtual void receiveMessage(const char *message_string) = 0;
static void staticReceiveMessage(const char *message_string, void **user_data);
protected:
+ /** Plugin status. */
typedef enum
{
STATUS_NONE,
@@ -61,10 +64,13 @@ protected:
STATUS_DONE
} EStatus;
+ /** Plugin shared memory. */
class SharedSegmentInfo
{
public:
+ /** Shared memory address. */
void *mAddress;
+ /** Shared memory size. */
size_t mSize;
};
@@ -73,42 +79,56 @@ protected:
std::string statusString();
void setStatus(EStatus status);
- // The quicktime plugin overrides this to add current time and duration to the message...
+ /// Note: The quicktime plugin overrides this to add current time and duration to the message.
virtual void setDirty(int left, int top, int right, int bottom);
+ /** Map of shared memory names to shared memory. */
typedef std::map<std::string, SharedSegmentInfo> SharedSegmentMap;
+ /** Function to send message from plugin to plugin loader shell. */
LLPluginInstance::sendMessageFunction mHostSendFunction;
+ /** Message data being sent to plugin loader shell by mHostSendFunction. */
void *mHostUserData;
+ /** Flag to delete plugin instance (self). */
bool mDeleteMe;
+ /** Pixel array to display. TODO:DOC are pixels always 24-bit RGB format, aligned on 32-bit boundary? Also: calling this a pixel array may be misleading since 1 pixel > 1 char. */
unsigned char* mPixels;
+ /** TODO:DOC what's this for -- does a texture have its own piece of shared memory? updated on size_change_request, cleared on shm_remove */
std::string mTextureSegmentName;
+ /** Width of plugin display in pixels. */
int mWidth;
+ /** Height of plugin display in pixels. */
int mHeight;
+ /** Width of plugin texture. */
int mTextureWidth;
+ /** Height of plugin texture. */
int mTextureHeight;
+ /** Pixel depth (pixel size in bytes). */
int mDepth;
+ /** Current status of plugin. */
EStatus mStatus;
+ /** Map of shared memory segments. */
SharedSegmentMap mSharedSegments;
};
-// The plugin must define this function to create its instance.
+/** The plugin <b>must</b> define this function to create its instance.
+ * It should look something like this:
+ * @code
+ * {
+ * MediaPluginFoo *self = new MediaPluginFoo(host_send_func, host_user_data);
+ * *plugin_send_func = MediaPluginFoo::staticReceiveMessage;
+ * *plugin_user_data = (void*)self;
+ *
+ * return 0;
+ * }
+ * @endcode
+ */
int init_media_plugin(
LLPluginInstance::sendMessageFunction host_send_func,
void *host_user_data,
LLPluginInstance::sendMessageFunction *plugin_send_func,
void **plugin_user_data);
-// It should look something like this:
-/*
-{
- MediaPluginFoo *self = new MediaPluginFoo(host_send_func, host_user_data);
- *plugin_send_func = MediaPluginFoo::staticReceiveMessage;
- *plugin_user_data = (void*)self;
-
- return 0;
-}
-*/
generated by cgit v1.2.3 (git 2.25.1) at 2024-12-12 00:28:59 +0000