本库适用于 Minecraft 1.18.2。其他版本的移植版本将陆续推出。如果您希望自行移植,欢迎提交拉取请求!
VideoLib
自诞生以来,Minecraft 的引擎……至少可以说有些“有趣”。它似乎缺乏许多标准功能,例如 GPU 网格缓存,以及在本案中提到的简单视频播放。本模组旨在解决这一问题,为模组开发者提供一个干净的 API,以便在他们的模组中使用预渲染的视频播放功能。
注意:本模组本身不提供任何功能。它仅作为供其他模组使用的库。
设置
一旦 Maven 依赖项配置完成,将会提供安装指南。值得注意的是,默认实现要求用户的系统上安装 VLC Media Player。
用法
要使用 VideoLib,您必须获取对 VideoManager 的引用。该视频管理器是所有与库交互的基础,对于模组的功能至关重要:
VideoManager videoManager = VideoLib.getInstance().getVideoManager();
VideoManager 可用于创建多个 VideoPlayer。由于视频播放存在性能开销,每个视频播放器都会使用唯一的 ID 向视频管理器注册。只有视频管理器才能创建新的 VideoPlayer 实例。
VideoPlayer videoPlayer = videoManager.getOrCreate(new Identifier("mymod", "my_video_player"));
每个 VideoPlayer 都有一个 getTexture() 函数,该函数返回一个 Minecraft 纹理标识符,可在实体渲染器(或任何其他使用非图集纹理的地方)中使用。此纹理会针对视频的每一帧自动更新,并且可以像其他任何纹理一样应用。
Identifier texture = videoPlayer.getTexture();
VertexConsumer consumer = vertexConsumers.getBuffer(RenderLayer.getEntityCutout(texture));
// 以任何您想要的方式渲染几何体
视频句柄
有多种方法可以让视频播放器开始播放,但大多数都围绕 VideoHandle 展开。视频句柄本质上是指向存储在外部位置的视频文件的指针,无论是在本地磁盘上还是互联网上的某个地方。要创建 VideoHandle,您需要一个 VideoHandleFactory。这可以从 VideoManager 中获取。
需要注意的是,并非所有视频句柄都能与所有视频管理器配合使用。请确保仅使用视频管理器工厂提供的视频句柄。(大多数 API 函数已经做到了这一点)。
VideoHandleFactory factory = videoManager.getVideoHandleFactory();
VideoHandleFactory 提供了两个主要功能:getVideoHandle(Identifier) 和 getVideoHandle(URL)。
-
getVideoHandle(Identifier) 期望来自任何模组的视频文件的资源标识符。该文件必须位于您的资源包的 videos 文件夹中。(例如:mymod:videos/myvideo.mp4)
-
getVideoHandle(URL) 期望找到视频的 URL。这可能是在互联网上,也可能在本地文件系统上。(例如:http://mywebsite.com/myvideo.mp4)。此文件必须可以通过 GET 请求直接访问。不允许使用 Google Drive 链接或其他需要用户导航下载页面的服务。
然后可以将视频句柄传递给视频播放器进行播放。
VideoHandle idHandle = factory.getVideoHandle(new Identifier("mymod", "videos/myvideo.mp4"))
VideoHandle urlHandle = factory.getVideoHandle(new URL("http://mywebsite.com/myvideo.mp4"));
videoPlayer.getMediaInterface().play(idHandle);
媒体播放器还提供接受标识符和 URL 的直接重载 play() 方法。这些只是创建视频句柄并播放它们的快捷方式。
播放控制
视频播放器提供了一组接口,允许更精细地控制媒体播放:MediaInterface、ControlsInterface 和 CodecInterface。可以通过以下方式访问它们:
MediaInterface mediaInterface = videoPlayer.getMediaInterface();
ControlsInterface controlsInterface = videoPlayer.getControlsInterface();
CodecInterface codecInterface = videoPlayer.getCodecInterface();
这三个接口提供了多种基本功能,例如 pause、play 和 setTime。有关这些 API 功能的详细信息,请参阅 javadoc。
事件
VideoLib 提供了一系列回调,会在视频播放期间的特定事件触发时调用。无论它们在原生代码中的何处触发,所有事件监听器都会在 Minecraft 客户端线程上调用。
VideoEvents events = videoPlayer.getEvents();
events.onBuffering(e -> {
LogManager.getLogger().info("Buffering!");
})
与播放界面类似,事件函数的详细信息也在 javadoc 中说明。
关于许可证的说明
VideoLib 的默认实现依赖于 VLCJ,其许可协议为 GNU GPL。这意味着 vlc 包中的所有代码均在 GPL 下授权。然而,仓库的其余部分(只要不直接依赖 vlc 包)则在 MIT 许可下授权。此外,vlc 包不被视为公共 API 的一部分,未来可能会移至单独的 Gradle 项目中。
计划中的功能
This library is for Minecraft 1.18.2. Ports for other versions will come in time. If you wish to port it yourself, pull requests are welcome!
VideoLib
Ever since its inception, Minecraft's engine has been... interesting, to say the least. It seems to lack many standard features such as GPU mesh caching and, in this case, simple video playback. This mod aims to remedy this, providing a clean API for mod-makers to use pre-rendered video playback in their mods.
Note: this mod provides no functionality on its own. It is simply a library for other mods to make use of.
Setup
An installation guide will be provided once the maven dependencies are setup. It's worth noting that the default implementation requires VLC Media Player to be installed on the user's system.
Usage
To use VideoLib, you must get a reference to a VideoManager. This video manager is the basis for all interactions with the library, and is vital to the functionality of the mod:
VideoManager videoManager = VideoLib.getInstance().getVideoManager();
The VideoManager can be used to create multiple VideoPlayers. Due to the performance overhead of video playback, each video player is registered with the video manager using a unique ID. Only the video manager can create new VideoPlayer instances.
VideoPlayer videoPlayer = videoManager.getOrCreate(new Identifier("mymod", "my_video_player"));
Each VideoPlayer has a getTexture() function, which returns a Minecraft texture identifier that can be used in an entity renderer (or anywhere else that non-atlas textures are used). This texture is automatically updated for every frame of the video, and it can be applied like any other texture.
Identifier texture = videoPlayer.getTexture();
VertexConsumer consumer = vertexConsumers.getBuffer(RenderLayer.getEntityCutout(texture));
// render geometry however you want
Video Handles
There are a number of ways to tell a video player to begin playing, but most of them revolve around the VideoHandle. A video handle is essentially a pointer to a video file stored in an external location, whether it be on the local disk or somewhere on the internet. To create a VideoHandle, you need a VideoHandleFactory. This can be obtained from the VideoManager.
It's important to note that not all video handles will work with all video managers. Make sure you're only using video handles provided by the video manager's factory. (Most API functions already do this).
VideoHandleFactory factory = videoManager.getVideoHandleFactory();
The VideoHandleFactory provides two primary functions: getVideoHandle(Identifier) and getVideoHandle(URL).
-
getVideoHandle(Identifier) expects the resource identifier of a video file from any mod. This file must be in the videos folder of your resourcepack. (ex: mymod:videos/myvideo.mp4)
-
getVideoHandle(URL) expects the URL where a video can be found. This may be over the internet or on the local filesystem. (ex: http://mywebsite.com/myvideo.mp4). This file must be directly accessible via a GET request. Google Drive links and other services where the user must navigate a download page are not allowed.
The video handle can then be passed to the video player for playback.
VideoHandle idHandle = factory.getVideoHandle(new Identifier("mymod", "videos/myvideo.mp4"))
VideoHandle urlHandle = factory.getVideoHandle(new URL("http://mywebsite.com/myvideo.mp4"));
videoPlayer.getMediaInterface().play(idHandle);
Media players also provide overloads of play() that take identifiers and urls directly. These are simply shortcuts for creating video handles and playing them.
Playback Control
Video players provide a set of interfaces allowing for finer control of media playback: MediaInterface, ControlsInterface, and CodecInterface. These can be accessed as follows:
MediaInterface mediaInterface = videoPlayer.getMediaInterface();
ControlsInterface controlsInterface = videoPlayer.getControlsInterface();
CodecInterface codecInterface = videoPlayer.getCodecInterface();
These three interfaces provide a multitude of essential functions, such as pause, play, and setTime. Details on these API features can be found in the javadoc.
Events
VideoLib provides a number of callbacks that trigger at certain events during video playback. Regardless of where they're triggered in native code, all event listeners are called on the Minecraft client thread.
VideoEvents events = videoPlayer.getEvents();
events.onBuffering(e -> {
LogManager.getLogger().info("Buffering!");
})
Like, the playback interfaces, event functions are detailed in the javadoc.
A Note on Licenses
The default implementation of VideoLib relies on VLCJ, which is licensed under the GNU GPL. This means that everything in the vlc package is licensed under the GPL. The rest of the repo, however, provided it doesn't directly depend on the vlc package, is licensed under the MIT license. Additionally, the vlc package is not considered a part of the public API, and it may be moved to a separate Gradle project at a later time.
Planned Features
-
Audio control.
- Right now, VLC directly pipes audio to your operating system, bypassing Minecraft all-together. I intend to change this.
-
Standardize supported formats.
-
Warn users when VideoLib fails to initialize (usually due to missing natives).
-
Rendering utility functions.
评论 0
登录后参与评分
还没有评论,来抢沙发吧