Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Adding some docs for libprimis headers #24

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 17 additions & 0 deletions slot.h
Original file line number Diff line number Diff line change
Expand Up @@ -105,6 +105,10 @@ struct Slot
}

virtual const char *name() const;

/**
* @brief The directory where textures are stored
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The convention I've used for @brief statements is a complete sentence ending with a period. I also would generally phrase the @brief for this as "returns the directory..." since that is more specifically what the function does, and then use the current phrase for the @return.

*/
virtual const char *texturedir() const
{
return "media/texture";
Expand Down Expand Up @@ -287,7 +291,20 @@ extern std::vector<Slot *> slots;
extern std::vector<VSlot *> vslots;
extern std::vector<int *> editingvslots;

/**
* @brief Extract or replace the shader parameter name, inserting if it doesn't exist, in `shaderparams`.
*
* Extracts the name from a global `shaderparams` whose type is `std::unordered_set<std::string>`.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Technically this global is called shaderparamnames.

For some additional context, this global set of shaderparamnames is only used by this function, is not cleaned up at any point, and is used specifically to assign the SlotShaderParam::name field. This object is used when handling map loading (when most slots are initialized) and when slot params are added while editing ( setshaderparam and reuseuniformparam CS commands).

* It performs the necessary "conversion" from `std::string` to `const char *`.
*
* If the name doesn't exist yet, it is inserted, then returned
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If the name doesn't exist yet or insert is true then the value will be inserted.

It appears that due to the specific behavior of unordered_set<std::string> compared to hashset<const char *> that this may be redundant, since strings which compare equal under strcmp or std::string::operator== can be allocated independent entries in a hashset<const char *> (or unordered_set<const char *>) but not in an unordered_set<std::string>. I'd need to do testing to verify this behavior.

*
* @param name The name to retrieve
* @param insert A bool value representing wether or not to replace it in the global shaderparams global; default true
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

whether*

* @return The corresponding shader name parameter in the `shaderparams` global set
*/
extern const char *getshaderparamname(const char *name, bool insert = true);

extern void setldrnotexture();

extern VSlot *findvslot(const Slot &slot, const VSlot &src, const VSlot &delta);
Expand Down